# Introduction Fin gives each of your users an AI agent that can chat, run tasks on its own and, with the user's signed approval, hold and trade funds. Your backend talks to Fin's REST API; your app keeps its own interface, login and users. ## How an integration works 1. **Create the user** with your own `userId`, using your API key. 2. **Sign them in.** After your login verifies the user, your backend opens a Fin session naming the wallet or passkey they signed in with. Apps without a login can have the user sign a message instead. 3. **Chat.** Send the user's message to start a run in their main conversation, and follow the agent's reply on the event stream or by reading the run. 4. **Approve actions.** When the agent wants to do something that needs the user's OK, the run pauses; show the user the approval and send their decision. Anything that moves money also needs their wallet's signature on a message the API gives you. 5. **Fund the agent.** The user creates the agent's wallet with one signature, deposits to it, and withdraws from it with a signed quote. The [quickstart](/quickstart) walks through steps 1–3 with a real request for each. ## Who owns what | Resource | What it is | | --- | --- | | Partner | Your company: its API keys, usage and limits. | | User | Your customer, named by your `userId`. | | Agent | The user's agent, created with them, with its own wallet. | | Session | Up to an hour of access to one user, opened by your backend. | | Conversation | A chat thread. Every user has a main one. | | Run | The agent working on one message. | | Automation | A task the agent runs on its own. | ## Your app and Fin | Your app does | Fin does | | --- | --- | | Log users in and show the interface | Run the agent and keep every conversation | | Keep the API key and session tokens on its server | Check sessions and signatures | | Show the user what they're approving and collect their signature | Hand you the message to sign and enforce exactly what was signed | | Send deposits from the user's own wallet | Give deposit addresses, send withdrawals and record receipts | Requests and responses are JSON, errors are [problem details](/errors), lists are paged with a cursor, and live updates arrive as server-sent events. ## Next - [Quickstart](/quickstart): your first agent reply. - [Authentication](/authentication): API keys, sessions, wallets and the security model. - [Deposits, withdrawals and trades](/wallet-transfers): moving money. - [Usage and limits](/usage-and-quotas): what your account can do at once. --- # Quickstart Create a user, sign them in and get the agent's first reply. This run has tools switched off, so it needs no wallet or funds. ## Before you begin From your deployment operator, get the API URL and an API key. If your app has no login of its own, also register the web origin your users sign in from. These examples use Bash, `curl`, `jq` and `uuidgen`, run from your server. Keep the API key and session tokens on your server. ```bash FIN_BASE_URL=https://api.example.test FIN_API_KEY=your_api_key FIN_USER_ADDRESS=0x0000000000000000000000000000000000000001 # the wallet your user signed in with ``` ## 1. Create the user `userId` is your own id for the user. It appears in every path, so use letters, digits, `.`, `_`, `:` and `-`, and never an email address. Calling this again returns the same user. ```bash curl --fail-with-body -sS -X POST "$FIN_BASE_URL/v1/users" \ -H "X-Api-Key: $FIN_API_KEY" -H 'Content-Type: application/json' \ -d '{"userId":"customer-123","name":"Example user"}' > user.json FIN_USER_ID=$(jq -er '.userId' user.json) ``` The user comes with their agent and a main conversation. They have no wallet yet; that comes later, when they fund the agent. ## 2. Sign the user in Your app has already signed the user in with its own login, so open their session by naming the wallet they used. Your API key vouches for them; they sign nothing here. ```bash curl --fail-with-body -sS -X POST "$FIN_BASE_URL/v1/users/$FIN_USER_ID/sessions" \ -H "X-Api-Key: $FIN_API_KEY" -H 'Content-Type: application/json' \ -d "$(jq -n --arg address "$FIN_USER_ADDRESS" \ '{controller:{kind:"evm",chainId:1,address:$address}}')" > session.json FIN_TOKEN=$(jq -er '.token' session.json) FIN_AUTH=(-H "X-Api-Key: $FIN_API_KEY" -H "Authorization: Bearer $FIN_TOKEN") ``` The first session registers this wallet as the user's for good: later sessions must name the same one, and it signs anything that moves money. The session lasts an hour; once it expires, requests answer `401 credential_expired`, so create a new one the same way. NEAR, Solana, Stellar, TON and Tron wallets and passkeys work too; see [Authentication](/authentication) for each `controller`. ### If your app has no login Let the user sign in with their wallet instead. Ask for a sign-in message: ```bash FIN_APP_ORIGIN=https://wallet.example.test # one of your registered origins curl --fail-with-body -sS -X POST "$FIN_BASE_URL/v1/users/$FIN_USER_ID/session-challenges" \ -H "X-Api-Key: $FIN_API_KEY" -H 'Content-Type: application/json' \ -d "$(jq -n --arg address "$FIN_USER_ADDRESS" --arg origin "$FIN_APP_ORIGIN" \ '{controller:{kind:"evm",chainId:1,address:$address},origin:$origin}')" > challenge.json ``` Have the user sign `message` exactly as returned. With viem in the browser: ```ts const signature = await walletClient.signMessage({ account, message: challenge.message }); // Send the signature to your backend, which finishes the sign-in below. ``` Then exchange the signature for a session within five minutes: ```bash FIN_SIGNATURE='' curl --fail-with-body -sS -X POST "$FIN_BASE_URL/v1/users/$FIN_USER_ID/sessions" \ -H "X-Api-Key: $FIN_API_KEY" -H 'Content-Type: application/json' \ -d "$(jq -n --arg id "$(jq -er '.challengeId' challenge.json)" --arg signature "$FIN_SIGNATURE" \ '{challengeId:$id,signature:{kind:"evm",signature:$signature}}')" > session.json ``` ## 3. Get the main conversation Every user has a main conversation. Single-chat apps send every message there. ```bash FIN_CONVERSATION_ID=$(curl --fail-with-body -sS \ "$FIN_BASE_URL/v1/users/$FIN_USER_ID/conversations/main" "${FIN_AUTH[@]}" | jq -er '.id') ``` To start a separate thread, use [Create a conversation](/api-reference/conversations/create). ## 4. Start a run A run is the agent working on one message. Generate an `Idempotency-Key` for this message and keep it: if the request times out, send it again with the same key and you get the same run back instead of a second one. ```bash FIN_RUN=$(curl --fail-with-body -sS -X POST "$FIN_BASE_URL/v1/users/$FIN_USER_ID/runs" \ "${FIN_AUTH[@]}" -H 'Content-Type: application/json' \ -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \ -d "$(jq -n --arg conversationId "$FIN_CONVERSATION_ID" \ '{conversationId: $conversationId, text: "Say hello in one sentence.", profile: {tools: []}, context: {timeZone: "America/New_York"}}')") FIN_RUN_ID=$(jq -er '.id' <<<"$FIN_RUN") ``` The answer is `202` with the run, status `running`: the agent works in the background. `profile.tools: []` switches tools off for this run; leave `profile` out to allow every tool. `context.timeZone` is the user's time zone as an IANA name; in a browser it is `Intl.DateTimeFormat().resolvedOptions().timeZone`. Send it with every message: the agent reads times like "9am" in that zone, and asks the user when it is missing. If your app draws trades, automations, the wallet, orders or saved contacts itself, add `context.renders` too (see [Render a reply](/streaming#render-a-reply)). To let the agent find recipients by name, add the user's saved contacts as `context.contacts` from your server (see [Contacts](/concepts#contacts)). Send `context.country` with every message too: the uppercase two-letter country code from your server's edge geolocation, never from the browser. If it is unavailable, leave it out. Tokenized-stock purchases require a country outside the United States and Canada and an operator-enabled `tokenized_stocks` flag. Once held, these assets can only be sold, never withdrawn or sent; see [Tokenized stocks](/concepts#tokenized-stocks) for the country rule when selling. ## 5. Follow the reply Open the conversation's event stream. It replays what already happened, so opening it after starting the run loses nothing. ```bash curl --fail-with-body -sSN "${FIN_AUTH[@]}" -H 'Accept: text/event-stream' \ "$FIN_BASE_URL/v1/users/$FIN_USER_ID/conversations/$FIN_CONVERSATION_ID/stream?cursor=0" ``` `agent.text_delta` events carry the reply as it is written; show them as temporary text. `agent.entry` carries the saved reply, and `run.ended` says the run is over. The stream stays open for later runs; press Ctrl-C to close it. See [Streaming and events](/streaming). Or poll the run instead of streaming: ```bash curl --fail-with-body -sS "$FIN_BASE_URL/v1/users/$FIN_USER_ID/runs/$FIN_RUN_ID" "${FIN_AUTH[@]}" ``` `status` is `running`, `paused` (waiting for an approval or answers), `completed`, `failed` or `aborted`. Once it is `completed`, `response.text` holds the agent's reply. ## When you turn tools on Some actions need the user's OK first. When the agent wants to take one, the run pauses (`paused`), an `approval.opened` event arrives, and the run lists it in `pendingApprovals`. 1. Read it with [Get an approval](/api-reference/approvals/get) and show the user exactly what it will do: the assets, amounts, destination and limits it lists. 2. If it moves money, it carries `authorization.message`. Have the user sign that message with their wallet. 3. Send the decision: [Approve an action](/api-reference/approvals/approve) (with `authorization: {controllerId, expiresAt, signature}` for a money action) or [Deny an action](/api-reference/approvals/deny). The run resumes on its own; don't start another one. Approving doesn't mean the action worked. Follow the run, and for a trade read [List trades](/api-reference/wallets/list-trades) with `runId=$FIN_RUN_ID` for its `status`. If the user takes longer than the message allows, read the approval again for a fresh message. An approval that expires stops the run (`aborted`). A trade needs the agent wallet first. The user creates it with one signature, or with the sign-in's own signature when you start sign-in with `createWallet: true`; see [Deposits, withdrawals and trades](/wallet-transfers#create-the-agent-wallet). ## When the agent asks questions With `ask_user_tool` enabled, the agent can pause for missing preferences. A `question.opened` event contains the questionnaire; the run lists its id in `pendingQuestions`. This is not an approval. 1. Read [Get a question](/api-reference/questions/get). Render each question's prompt and options, one question at a time. Only `multiple: true` permits multiple options. 2. Collect an answer for each question the user answers: its `id` and selected option `values`, or `values: []` with `customText` (up to 2,048 characters). Custom text and option values are mutually exclusive. A question the user skips gets no answer. 3. Call [Answer a question](/api-reference/questions/answer) with a fresh UUID `Idempotency-Key` and `{ "kind": "answers", "answers": [...] }`, or `{ "kind": "skip" }` when the user skipped every question. Keep the same key and body for retries. The response is the updated question resource; follow the original run, rather than starting another one. A questionnaire has one to five questions, each with two to six options. The first accepted submission wins; a competing answer gets `409 question_not_pending`, and reusing a key with different content gets `409 request_key_conflict`. Invalid option values, or an answer to a question the card doesn't ask, get `400 invalid_question_answer`. After expiry (24 hours) or cancellation, answering gets `410 question_closed`. Refresh the resource after a refusal. Answers do not sign a transaction, approve an action or grant financial consent. If answering gets `503 execution_unavailable`, retry with the same key and body rather than creating another run. A Stop racing an accepted answer can abort the run while preserving that answer; read the question and the original run to distinguish their outcomes. ## Keep going - [How Fin works](/concepts): users, conversations, runs, approvals and money. - [Streaming and events](/streaming): history and reconnecting. - [Deposits, withdrawals and trades](/wallet-transfers): funding the agent and taking money out. - [Automations](/automations): tasks the agent runs on its own. - [Errors](/errors): every refusal and what to do about it. --- # How Fin works The pieces of Fin, what each one is for, and how they fit together. ## Users and their agent You create a **user** with your own `userId`, and every path names them by it. The same `userId` under another partner is a different user. Each user gets one **agent** and one **main conversation** when you create them. A **session** lets your backend act for a signed-in user for up to an hour. It is separate from the user's wallet signature, which is what money needs; see the [security model](/authentication#security-model). ## Conversations and runs A **conversation** is a chat thread between the user and their agent. It keeps every message, run and approval. The main conversation is where single-chat apps send everything; create more for separate topics, and delete one the user no longer wants: it leaves their list, its history stays readable, and it takes no new messages. Deleting the main conversation gives the user a new, empty one, so read the main conversation again after a delete rather than keeping its id. A **run** is the agent working on one message. You start it with the user's text and it answers `202` straight away; the work happens in the background. A run moves through these statuses: | `status` | Meaning | | --- | --- | | `running` | The agent is working. | | `paused` | Waiting for an approval decision or answers to the agent's questions. | | `completed` | Finished. `response.text` holds the reply. | | `failed` | Ended with an error. | | `aborted` | Cancelled, or a pending approval or questionnaire expired. | A run keeps its id while it pauses and resumes. Call [Get a run](/api-reference/runs/get) at any time to catch up; it returns the original message, the status, the reply, `pendingApprovals` and `pendingQuestions`. `output` holds structured output when you asked for one with `profile.outputContract`; it is separate from the text reply. `origin` names the automation that started a run: its `automationId`, the automation run it carried out (`automationRunId`) and the automation's `name`; it's `null` for a run the user started with a message. `reads` says what the agent read while it worked, by the tools whose calls completed: `account` (the user's own balances, holdings, orders or positions) and `prices` (market prices). It's empty when the agent read neither. Use both to show the agent's activity, such as an automation run that moved no money. The agent sees the conversation's history, up to the model's context window. ### Feedback on a reply The user can send feedback on a run's reply with a thumb. Once the run has ended (`completed`, `failed` or `aborted`), call [Send run feedback](/api-reference/runs/send-feedback) with `{ "rating": "up" }`, or `{ "rating": "down" }` with an optional `reason`. A run that is still working or waiting (`running` or `paused`) answers `409 run_active`; wait for `run.ended`. The reason is one of a fixed list and never free text: | `reason` | The reply was | | --- | --- | | `wrong` | Incorrect. | | `unhelpful` | Not what the user asked for. | | `slow` | Too slow. | | `unsafe` | Risky or inappropriate. | | `other` | None of these. | A reason goes with `down` only; with `up` the request is refused with `400 invalid_input`. A run has one set of feedback. Sending again replaces it, so the same call changes it and a retry is safe, and [Delete run feedback](/api-reference/runs/delete-feedback) deletes it. Get a run and List runs return it as `feedback` (`rating`, `reason`, `createdAt`, `updatedAt`), `null` until there is any, so a page that reloads can show the thumb the user chose. A run that is not the user's answers `404`, as for any other run. Feedback changes nothing about the run and needs no approval or signature. Fin's operators see feedback in totals and by reason, and can open a run that got a thumbs-down to see what happened, so tell users that a thumbs-down may be reviewed. ### Sending a message while the agent works A conversation has one run at a time: starting another while a run is `running` or `paused` answers `409 run_active`. A user who types while the agent works has two choices, and your chat offers either or both: - **Queue it.** Keep the message in your app and send it with Start a run once `run.ended` arrives. The queue is yours: order it, let the user edit or delete what waits, and send one message per run. Pause it after a run ends `aborted` or `failed` rather than sending into the same trouble. - **Steer the run.** Call [Steer a run](/api-reference/runs/steer) with `{ "text": … }` and the run's id from `run.started`. The agent reads it at its next step, in the same run: it answers `202` with the run, the message listed in `steers` as `pending`, and `run.steered` (with the message's `steerId`) lands in the conversation where the agent read it. Send an `Idempotency-Key` (a UUID) so a retry sends it once. While a message waits, the agent finishes what it is doing but starts nothing that would need the user, and nothing destructive: a call that needs an approval, cancels an order, archives an automation or asks a question is skipped, so nothing acts and no card opens on top of a message the agent has not read. If the run is waiting on an approval when the message arrives, the message declines it: the approval is denied with the reason "The user sent a new message instead." and nothing it proposed runs. If it is waiting on a question, the question is skipped. Either way the run carries on with the message. A message never approves anything, however it is worded. A run that has ended, or is finishing, answers `409 run_not_active`: send the text with Start a run instead. If the run ends before the agent reads a message (the user stops it, or it fails), the message is `dropped` in `steers` and never gets a `run.steered`; put it back in front of the user. Steering is off unless Fin turns it on for your users: until then the call answers `403 steering_disabled`, and queueing still works. ### Talking instead of typing A user who would rather say what they want than type it can record it. Call [Get voice input](/api-reference/voice/get) first and show a microphone only while `status` is `available`; `disabled` means voice input is not turned on for the user, and `unavailable` that the deployment has no speech model. Record at most `maxSeconds` (a minute) and send it in one of `formats`, the types the deployment's speech model decodes. NEAR AI's Whisper takes `audio/ogg` with Opus (what Firefox records) and `audio/wav`, not the WebM Chrome, Edge and Safari record or the MP4 older Safari records, so a page in those browsers converts its recording to WAV first: decode it with Web Audio and write 16-bit mono PCM, where 16 kHz keeps a minute under 2 MB. Send the bytes to [Transcribe a recording](/api-reference/voice/transcribe) with that type as `Content-Type`; any other type is refused with `400` before anything is charged. Each format has its own `maxBytes`, a minute of it with room to spare: 1.5 MiB of compressed speech, 6 MiB of WAV. Fin waits up to a minute for its speech model, so give the call 75 seconds before giving up; one abandoned sooner is still charged. It answers `{ "text": … }`: put it where the user writes, at their cursor, for them to read, change and send with Start a run, or Steer a run while the agent works. Nothing reaches the agent until they send it, so a misheard word is theirs to fix first. An empty `text` means no speech was heard: say so and let them try again. The recording goes to the deployment's own model provider, never the browser vendor's speech service, and Fin keeps neither the audio nor the text. Each transcription is an AI model call on the user's budget: `429 budget_exhausted` when it has no room, `429 rate_limited` with `Retry-After` past the user's hourly or daily transcriptions, `413` over the format's `maxBytes`, and `503 provider_unavailable` when the speech model did not answer, which is worth one retry of the same recording. `403 voice_disabled` and `503 voice_unavailable` mean the microphone should not be shown. ## Approvals When the agent wants to take an action that needs the user's OK, the run pauses and an **approval** opens. It lists exactly what the action will do. Show that to the user and send their decision; the run then resumes on its own. A money action also needs the user's signature on the approval's `authorization.message`. The agent can propose a withdrawal too: to the user's main wallet, or to an exact address the user gives. That address must be one the user sent with this message: in its text, in a typed answer to the agent's question, or among the `context.contacts` sent with it. An address that appeared only in something the agent read opens no approval; the agent asks the user instead. Its approval names the full destination, and once approved it cannot change. Every approval keeps its `fingerprint`, the SHA-256 digest of exactly the action it decides. An approved money action also names the sign-in wallet that signed it, in `signedBy`. To show one chat's approvals, decided or not, list them with `status=all&conversationId=…`. ## Questions The agent can ask for missing preferences using `ask_user_tool`: one card with one to five questions, each with two to six options. It asks only for what has no default: a recurring buy that names no time runs at 9:00 AM in the user's time zone and ends after 30 days, and its approval card shows both. Show one question at a time; a tap on a single-choice option can answer it and move on. Allow multiple selections only when `multiple` is true, and offer custom text instead of the listed choices. Submit the answers together after the last question, leaving out any the user skipped, or skip the whole card. The same run resumes afterward. An option may carry `description`, one line on what it means, and at most one option per question is `recommended`, with why in its description; show the recommendation, never preselect it. A choice between ways to buy may carry `picture`, a small drawing to show over it: `schedule` for a regular buy, `dip` for buying only after a fall, `once` for one buy now. It is a hint only: an app that draws none shows the same choices as text. A question with `amount: { min, max, step, unit }` asks for one amount: `min`, `max` and `step` are decimal strings, `unit` is `usd` or a token symbol, and its options are presets whose values are decimal strings within the bounds. Offer a slider between `min` and `max` in steps of `step`; answer a preset with its value, and any other amount as `customText`, a plain decimal in that unit (`"130"`). An amount question never sets `multiple`. Questions expire after 24 hours; cancelling the run closes them too. An answer supplies information, never approval or permission to spend. ## Contacts Send the user's saved contacts in `context.contacts` when you start a run, so the agent can resolve "send 5 USDC to Alice" to a saved address. Each contact is `{ id, name, address, network }`, with `network` in your app's own naming (`eth`, `base`, `near`, `near_intents`). A message carries at most 200 contacts in 64 KiB; `name` is up to 64 characters, `id` and `address` up to 128 printable ASCII characters without spaces, and `network` up to 32 lowercase characters. Unknown fields, repeated ids or anything over a limit refuse the whole request with `400 invalid_input`, and no run starts. Contacts belong to that one message. The agent reads them through its `contacts_list` tool; a later message without them has none, and the agent asks the user for an address instead of reusing an earlier one. Read them from your own server for every message rather than trusting what the browser sends. A retry with the same `Idempotency-Key` answers the run the first attempt started, with that attempt's contacts, even when the list changed in between. Names and addresses are treated as untrusted data: when several contacts match, none does, or the contact's network does not fit the asset, the agent asks the user. A contact authorizes nothing. Any action that pays an address still opens an approval showing the exact address and network, and the user decides there. When the user asks who is saved, the lookup's result is the list. Draw it as a card and add `contacts` to `context.renders`, and the reply leaves the names and addresses to the card ([Render a reply](/streaming#render-a-reply)). ## Perps availability Send `context.perpsAllowed: true` or `false` when you start a run to report whether your server's current region policy permits that user to add perpetual-futures exposure. Compute it on your trusted server; do not accept a browser-selected value. The report belongs to that message and is saved with its observation time. Omitting it on a new message reports no current permission and leaves the user's latest saved observation unchanged. Unlike contacts, this value is part of retry identity. Retry with the same `Idempotency-Key` and the same value to receive the original run without refreshing its observation time. Changing the value, adding it or omitting a previously supplied value under the same key answers `409 request_key_conflict`; start a new run with a new key for a new report. The latest observation wins by observation time, not by which request finishes last. This flag never authorizes spending or replaces financial approval. Account reads do not depend on a region report; withdrawing remains an exit rather than permission to grow exposure. ## Tokenized stocks Send `context.country` with every message, using the user's country from your server's edge geolocation, not a browser-supplied value. It is an uppercase two-letter ISO 3166-1 country code, such as `GB`. Leave it out when geolocation is unavailable; without a country, Fin refuses tokenized-stock trades. Ondo's tokenized U.S. stocks and ETFs are offered only for messages reporting a country outside the United States (`US`) and Canada (`CA`), and purchases also require an operator to enable `tokenized_stocks` for the user. Selling existing holdings does not require that flag, but still requires an allowed country. These assets can never be withdrawn or sent to another wallet, only sold. Enabling the flag does not override the country restriction. Country belongs to that one message. A retry with the same `Idempotency-Key` answers the run the first attempt started, with that attempt's country, even if geolocation changed in between. A swap or limit order the user makes from your own screen takes the same fact for that one request: send `context.country` with Get a swap quote and again with Swap tokens, or with Prepare an order and again with Place an order, to trade a tokenized stock. Fin checks it on arrival and keeps it nowhere. A retry that finds its swap or order needs none. ## Money The agent has its own **wallet**, which the user creates with one signature. - A **deposit** funds the wallet from an address the API gives you. - A **withdrawal** sends funds out, after a quote and the user's signature. The agent can also propose one in a run; the user approves and signs it like a trade. - A **trade** is made by the agent during a run, with the user's approval. - A **limit order** is a trade that waits at the provider for its price. The agent places one with the user's approval, or the user places one from your own screen with their signature. Each has its own record with a status and receipts. A reply from the agent or a finished run never proves money moved: read the deposit, withdrawal, trade or order. [Deposits, withdrawals and trades](/wallet-transfers) covers all of them. ## Automations An **automation** is a task the agent runs on its own, on a schedule, when a condition becomes true, or when your system sends an event. The user creates it by asking the agent. Each time it runs it starts a fresh conversation. It can trade without asking each time only within limits the user signed for it when it was created. New automations with those trading limits are restricted to clock or first-entry-swap-pair 1Click triggers, with a reviewed push-only exit exception. Only `kraken.asset_price` and `consensus.asset_price` readers with `delivery: "push"` may be referenced exclusively by `rule.exit.push.readers`; their asset/quote pair must match each exit action's pinned input/output tokens. They cannot appear in the entry condition at any depth or in either operand, or in `reader_update` wakes. Entry and unused readers remain pinned-token 1Click readers; entry conditions/update wakes use the first entry swap's quoted pair, and webhook/event wakes are refused. Any trading contract's entry condition may also read another venue the policy worker reads itself, on a clock; see [cross-venue triggers](automations.md#cross-venue-triggers). Push feeds only decide when a contract-backed exit gets checked. Fin independently checks the guard against the signed quote's fee-neutral ratio of per-token USD prices, not net executable amounts; entry conditions use those same exact USD prices. Clock-only entries with no price condition use the quote's signed timestamp instead of its prices. A payout-only schedule uses a dry canonical USDC → wNEAR reference preview as time evidence; it does not add a trade or change the payout. There is no tolerance band, and freshness and scheduled wakes use Fin's trusted clock. An outage cannot authorize a trade and leaves work eligible for a later check. Automations without a contract retain their source and event support without permission to spend. See [Automations](/automations). Fin proves the current condition, not a “becomes true” trigger's prior transition. That history remains scheduler-side, bounded by independently enforced once-only/run-count/cooldown and financial limits. ## Suggestions **Suggestions** are the moves Fin suggests on the user's whole account: an order to move or cancel, an automation to pause or change, money to swap, protect or put on a schedule. Fin reads the account in the background whenever it changes, checks every move the model proposes against what the user holds, fills in every figure itself and computes each move's exact review terms. Pages read them at once, each getting the moves that belong on it; each read of a changed account spends one small model call from the user's AI budget. Every user has them. A suggestion moves no money and starts no run. See [Suggestions](/suggestions). ## Notifications A **notification** is one thing Fin tells the user while they are away: an approval or a question waiting for them, an automation's report, money that moved, a problem with an automation, or the agent's reply in a chat they left. Each has its text ready to show and a read state shared by every device. Your app shows them in an inbox with the user's session, and your server reads every user's notifications from one feed with your key to ping their devices. A notification grants nothing: opening one leads to what it is about. See [Notifications](/notifications). ## Events Everything that happens in a conversation is saved as an **event**: messages, runs, approvals and trade updates. Read them as pages or follow them live on a stream; see [Streaming and events](/streaming). Fin never calls your servers. ## Budgets and limits Running the agent costs AI usage. Each user has a daily and monthly **budget** for it, and your partner account has shared limits on requests, runs, streams and spend. These are separate from the money in the user's wallet. See [Usage and limits](/usage-and-quotas). A budget or spend limit can stop work at two moments: - **Before a run starts**, Fin refuses the message with `429 budget_exhausted`: the user's budget has nothing left, or an operator froze it. - **While a run is working**, its next model request can find a limit with no room for it. The run ends `failed`, and `failure.code` on its `run.ended` event (and on [Get a run](/api-reference/runs/get)) names the limit, so your app can say why instead of showing a model error: | `failure.code` | What has no room | Clears | | --- | --- | --- | | `daily_budget_exhausted` | The user's budget for today. | At midnight UTC, or at once when an operator raises it. | | `monthly_budget_exhausted` | The user's budget for this month. | At the start of next month (UTC), or at once when an operator raises it. | | `budget_frozen` | An operator froze the user's budget. | At once, when the operator lifts the freeze. | | `partner_daily_budget_exhausted` | Your partner account's spend limit for today. | At midnight UTC. A raised limit applies from the next UTC day. | | `partner_monthly_budget_exhausted` | Your partner account's spend limit for this month. | At the start of next month (UTC). A raised limit applies from next month. | A limit stopped the run; the model did not fail. What the run already did stands, a trade the user approved included, so read their trades and receipts before they ask again. A request is refused when what is spent and reserved, plus the most it could cost, would pass the limit, so a limit can clear a little early when another run's reservation settles. Sending the message again ends the same way, or is refused with `429 budget_exhausted`, until the limit clears. --- # Base URL Use the API origin your deployment operator gives you, and append each operation's path to it: ```text https://{your-deployment} ``` Creating a user, for example, is `POST /v1/users`. Paths about one user start with their id, your own `userId`, as in `GET /v1/users/{userId}/runs`. The documentation site is a separate origin and does not serve API requests. --- # Authentication Every request carries your API key. Requests about a user also carry that user's session token: | Header | What it is | | --- | --- | | `X-Api-Key: fin_…` | Your API key. Identifies your app. Keep it on your server. | | `Authorization: Bearer fin_session_…` | A user's session token, from [Create a session](/api-reference/users/create-session). | A few calls need only the API key: Create a user, Start wallet sign-in, Create a session, Get your AI usage and Get your rate limits. ### API keys Your deployment operator issues your keys. A key is shown once, when it is created, and can carry an expiry. To rotate one, get a new key, switch your backend to it, then have the old one revoked; a revoked key can keep working for up to 30 seconds. Never put an API key in browser code, a URL or a public repository. ### Sign a user in Create the user once with [Create a user](/api-reference/users/create) (`POST /v1/users`, body `{userId, name}`). Then open a session for them whenever they use your app, in one of two ways: - **Your app has its own login.** After your login verifies the user, call `POST /v1/users/{userId}/sessions` with `{"controller": …}`: the wallet or passkey they signed in with. Your API key vouches for them, so they sign nothing extra. - **Your app has no login.** Call [Start wallet sign-in](/api-reference/users/session-challenge) for the user's wallet, have them sign the returned `message` exactly as it is, and send `{challengeId, signature}` to `POST /v1/users/{userId}/sessions`. Either way you get a `token`. Sessions last one hour and cannot be refreshed. A request with an expired token answers `401` with reason `credential_expired`: create another session the same way. A `401` with no reason means the token was revoked or was never valid. Revoke the session when the user logs out of your app. Logging out deletes nothing and does not stop work already started. The first session registers the user's wallet (their *controller*) for good. Every later session must name the same wallet, and that wallet signs everything that moves money. Only vouch for users your login has really verified, with the wallet they really used. If your app proxies browser requests, allow only the user operations the browser needs, require its verified session, and bind any `{userId}` path to that session. Never attach your API key to arbitrary browser-selected Fin paths: even a signed-in user must not call partner-only enrollment, session issuance, provider-session or partner usage operations. Provision and vouch inside your trusted login handler, deriving the user and controller from the login it verified rather than from a browser-supplied identity. ### Supported wallets | Wallet | `controller` | `signature` | How the wallet signs | | --- | --- | --- | --- | | EVM | `{kind: "evm", chainId, address}` | `{kind: "evm", signature}` (0x, 65 bytes) | ERC-191 personal message signing | | NEAR | `{kind: "near", accountId}` | `{kind: "near", publicKey, signature, nonce}` | NEP-413 `signMessage({message, recipient, nonce})` with the `recipient` the API returns and 32 random bytes as `nonce` | | Solana | `{kind: "solana", address}` | `{kind: "solana", signature}` | `signMessage` over the UTF-8 bytes | | Stellar | `{kind: "stellar", address}` | `{kind: "stellar", signature}` | SEP-53 message signing | | TON | `{kind: "ton", publicKey}` | `{kind: "ton", signature, address, domain, timestamp}` | TON Connect `signData({type: "text", text: message})`, `domain` one of your registered origins' hosts | | Tron | `{kind: "tron", address}` | `{kind: "tron", signature}` (0x, 65 bytes) | TIP-191 `signMessageV2` | | Passkey | `{kind: "webauthn", credentialId, publicKey, rpId, origin}` | the WebAuthn assertion | a P-256 or Ed25519 assertion whose challenge is the SHA-256 of the message | Ed25519 signatures are 64 bytes in padded standard base64. A NEAR account must sign with one of its current full-access keys. A passkey must belong to one of your registered origins. ### Security model Three things authorize three different kinds of action: | Credential | Lets you | Cannot | | --- | --- | --- | | API key | Create users, open sessions, read your usage | Read or act for a user without their session | | Session token | Everything a signed-in user can do: chat, start and cancel runs, read history, manage automations | Move money or create the agent wallet | | The user's signature | Create the agent wallet, withdraw, swap, place a limit order, approve a trade | Anything other than the one request it signs | | An agent 1Click session, from [Get a 1Click session](/api-reference/wallets/create-session) | Read the agent wallet at 1Click: balances, history and orders; cancel its open orders | Move funds: every withdrawal, swap, order and trade still needs the user's signature | Money only moves with the user's signature over that exact request, or within limits the user signed for an automation ahead of time. The API gives you the message to sign each time; show the user what it covers before they sign. A signature is valid for about five minutes and works once. Keep the API key and session tokens on your server (or in HttpOnly cookies) and proxy browser requests through your backend; never put them in browser JavaScript, URLs or local storage. The same goes for an agent's 1Click tokens. Fin cannot revoke those once it has issued them: each lasts until its `refreshTokenExpiresAt`, so delete them when the user signs out. Fin never calls your servers, so read a resource again (or follow the event stream) to see changes, with a live session. --- # Pagination 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. Most lists are newest first. A conversation's events are oldest first, so you can replay them in order. --- # Idempotency 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`. | Operation | `Idempotency-Key` | | --- | --- | | Create a deposit, Create a deposit address, Withdraw funds, Swap tokens, Place an order | Required. For a withdrawal or a swap, use the `requestKey` from the quote; for an order, the one from Prepare an order. | | Create a conversation, Start a run | Optional, but without it a retry creates a second one. | Create a user and Create the agent wallet need no key: they return the existing user or wallet. Get a 1Click session needs none either: every call is a separate session, and one lost on its way to you simply expires unused. Report a deposit transaction records nothing, so a repeat is safe. Approving or denying is a single decision; a repeat answers `409 approval_not_pending`. After a lost money response, find what happened before trying again: list deposits or withdrawals with `requestKey=`. Never retry money requests automatically with a new key. --- # Rate limits 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). When a limit is reached the API answers `429` with a `reason` and, when it can tell, a `Retry-After` header. Wait and retry the same request. See [Usage and limits](/usage-and-quotas) for the details. --- # Versioning 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. Nothing you rely on disappears without notice. An operation or an enum value that is going away is announced in this reference at least 30 days ahead: the operation is marked deprecated and says the date after which it is removed, and what to use instead; a value is named, with its date, on the schema it belongs to. The full list is `x-fin-retirements` in [`/openapi.json`](/openapi.json). Any other breaking change ships as a new API version with a list of what changed. Send `X-Request-Id` (8–64 characters of `[A-Za-z0-9._-]`) to trace a request; the response echoes the id Fin used. Quote it when you report a problem. Send `X-End-User-IP` and `X-End-User-Agent` with each request to say who is on the other end: the address and user agent your own server saw for the person using your app. Fin records them beside the request so that a security question about an account can be answered later, and uses them for nothing else — not rate limits, sign-in or any decision. Both are optional; an address that is not a valid IPv4 or IPv6 address is ignored, and the user agent is kept up to 512 characters. Send what your server observed, never a value your client supplied. With the SDK, pass `endUser: { ip, userAgent }` in each call's options ([call options](/sdk-reference#call-options)). --- # Errors 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. ```json { "type": "urn:fin:error:conflict", "title": "Conflict", "status": 409, "reason": "run_active", "requestId": "0192…", "retryable": false } ``` - `run_active` (409) — a run already holds this conversation - `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it - `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation - `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After` - `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again - `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed - `automation_changed` (409) — the automation changed while this request was handled; read it again and retry - `automation_held` (409) — an operator holds the automation; it fires again when released - `automation_invalid` (409) — the automation's definition cannot run as written - `automation_paused` (409) — the automation is paused; resume it first - `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook - `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have - `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later - `run_not_active` (409) — the run named in the path is not the conversation's live run - `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount - `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote - `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again - `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again - `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again - `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used - `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands - `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands - `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands - `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again - `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request - `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission - `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account - `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead - `conversation_deleted` (410) — the conversation was deleted; its history stays readable - `automation_deleted` (410) — the automation was deleted - `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat - `credential_expired` (401) — the user token has expired; obtain a fresh one - `account_disabled` (403) — an operator disabled the account - `perps_disabled` (403) — perps is not enabled for this user - `prediction_disabled` (403) — prediction-market trading is not enabled for this user - `solana_disabled` (403) — Solana trading is not enabled for this user - `no_account` (404) — the user has not opened the account this call reads; open it first - `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends - `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets - `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in - `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket - `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again - `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again - `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it - `voice_disabled` (403) — voice input is not turned on for this user; let them type instead - `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead - `provider_unavailable` (503) — an external provider the call depends on did not answer - `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network - `invalid_input` (400) — the body or query failed validation; `issues` names each field - `internal` (500) — a fault on our side; quote `requestId` when reporting it - `partner_key_required` (401) — no `X-Api-Key` header was sent - `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked - `subject_mismatch` (403) — the `{userId}` in the path is not the token's user - `origin_rejected` (403) — a browser `Origin` other than the configured web origin - `permission_required` (403) — the verified credential is not permitted to make this call - `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization` - `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first - `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off - `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off - `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing - `limit_orders_disabled` (403) — limit orders are not enabled for this user - `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated - `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that - `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed - `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound - `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed - `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed - `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After - `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity - `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After` - `invalid_cursor` (400) — the `cursor` is not one this list minted - `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices - `question_closed` (410) — the questionnaire expired or was cancelled - `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice - `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects - `brief_not_found` (404) — no market brief job with this id was created with your partner key - `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After` - `market_briefs_disabled` (403) — market briefs are not turned on for your partner key - `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read --- # Events 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=`. - `run.started` — Opens a new run: the engine admitted it and is about to process the input, whether an ordinary turn or an automation firing. Emitted once, at admission — a run resumed after an approval does not get a second one. `run.ended` closes what this event opened. - `run.ended` — The root run reached a terminal state: completed, failed or aborted. Its runId is the same as run.started and every pause/resume. Waiting for approval emits run.paused instead. Accounting includes all continuation segments. - `run.paused` — The run is waiting for human input or approval. Its identity and original request remain unchanged. - `run.resumed` — An approval decision resumed the same root run. No new instruction or run identity was created. - `run.steered` — The agent read a message the user sent while the run was working (Steer a run). Emitted at the agent's next step, before its next reply, so it lands in the conversation where the agent saw it; `steerId` matches the run's `steers` entry. Several messages sent within one step each get their own event, in the order sent. The same run continues; a message the run ended before reading never gets one. - `agent.entry` — One durable message in the conversation: the user's message, the assistant's completed reply, or a tool's display text once it resolves. Streaming assistant text arrives first as `agent.text_delta` and lands here only when the turn completes. - `agent.text_delta` — A chunk of the assistant's reply while it is still generating. Delivered live only — never written to the durable journal or replayed on reconnect — and superseded by the complete text in the `agent.entry` that follows. - `tool.call` — The assistant asked to call a tool. Emitted once the call is committed to the conversation, before it runs; `approval.opened` follows if a human must decide first, otherwise the call proceeds straight to `tool.result`. - `tool.result` — One tool call resolved: `outcome` says what happened (completed, denied, parked for approval, or failed). Immediately followed by an `agent.entry` (role `tool`) carrying that outcome's own display text. - `approval.opened` — A tool call is parked, waiting on a human decision. Carries the terms the approval card renders: the call's input, a summary, and the authorization contract in effect, if any. `approval.decided` or `approval.expired` closes it. - `approval.decided` — The user, or a partner integration, approved or denied a parked approval. `approve` says which way; a denial may carry `reason`. Consuming the decision to execute the tool follows as `approval.consumed`, but only when the decision was an approval — a denial never reaches consumption. - `question.opened` — A questionnaire is waiting for the user. Its full content is durable and replayable. - `question.answered` — The user answered or skipped a questionnaire; its accepted result is durable. - `question.closed` — A pending questionnaire expired or was cancelled. - `approval.consumed` — The approval was spent to authorize its tool call, immediately before that call runs. This is when the call is authorized, not when it finishes: the call can still fail after this event lands, and nothing here rolls it back. Marks the approval used; it cannot authorize a second execution. - `approval.expired` — A parked approval lapsed before anyone decided: its deadline passed, or the run it belongs to stopped while it was still pending. - `automation.fired` — An automation triggered this conversation's run. Emitted once, immediately before the `run.started` it precedes, naming the automation and its name at fire time. - `intents.settlement` — A later, independently verified financial fact about one leg of an authorized swap — settled, refunded, or never executed — never inferred from the model's own tool result. Appended whenever the provider confirms the outcome, independent of the run that requested it; `legId` and `operationId` join it back to its financial request, progress and authorizing approval. Archived receipts retain their original `occurrenceId`. - `intents.progress` — Best-effort, display-only progress for an authorized swap, between approval and its settlement receipt: freezing the plan (`planning`), the frozen legs (`planned`), then each leg's own stage (`stage`). Never gates execution and may arrive out of order or not at all; an `intents.settlement` receipt always takes precedence, and a terminal outcome is never reported here. - `perps.reconciled` — A later, independently verified answer to an approved perps order, cancellation or withdrawal whose own `tool.result` was left unconfirmed — never inferred from the model's own tool result. Appended once, by recovery, in the same commit that records the request's final outcome, independent of the run that made the call; `callId` joins it to that call's `tool.result`, `approvalId` to its approval, and `operationId` to its financial request. `result` has the shape the tool itself returns; show it in place of the call's earlier unconfirmed result. - `prediction.funding` — Recovery's latest view of an approved `prediction_fund` call, appended whenever it changes, independent of the run that made the call: the first leg's verified 1Click outcome (native Base USDC delivered to Polymarket's bridge, refunded, or not executed) and every transaction the bridge reports at the pinned deposit address, each `COMPLETED` one checked against its canonical Polygon receipt. Delivery to the bridge is not pUSD funding, a bridge `FAILED` is not a refund, and attribution of any bridge transaction to this funding stays unknown. `callId` joins it to that call's `tool.result`; show the latest in place of it. - `prediction.withdrawal` — Recovery's latest view of an attempted owner-approved pUSD withdrawal, independent of the run: its outgoing Polygon transfer receipt, what the bridge reports, and arrival at the unique linked 1Click deposit address. Only that deposit's own receipt establishes a credit or refund into the agent's confidential Intents wallet. A bridge status alone is not a receipt. Replace the original tool result by callId; recovery never signs or resends. - `composite.progress` — Best-effort display snapshot of an approved basket's pieces (`composite_execute`), appended after a piece changes state: each piece `todo`, `live`, `done`, `bad` or `skip`. Revision orders snapshots for the same call; ignore an older one. The call's own `tool.result` is the authoritative outcome of every piece, and each piece's own venue events keep their meaning; progress grants no execution permission. - `solana.progress` — Best-effort display snapshot derived from committed Solana funding, swap or sweep facts. Revision orders snapshots; repeated unchanged observations are omitted. A confirmed funding phase is only delivered SOL, and a confirmed swap phase does not establish sweep settlement. Final tool outcomes and solana.reconciled remain authoritative; progress grants no execution permission. - `solana.reconciled` — A later, independently verified answer to an approved Solana buy, sell or withdrawal whose own `tool.result` was left unconfirmed — never inferred from the model's own tool result. Appended once, by recovery, in the same commit that records the request's final outcome, independent of the run that made the call; `callId` joins it to that call's `tool.result`, `approvalId` to its approval, and `operationId` to its financial request. `result` has the shape the tool itself returns, with its `solana` detail; show it in place of the call's earlier unconfirmed result. - `prediction.order` — The latest observation of a Polymarket order. Replace the original placement call's result, joined by `callId`, with `result`. A match is not settlement; cancellation stops only the unmatched part and does not reverse earlier fills. Observations can arrive after the run ends. --- # Streaming & events Everything that happens in a conversation is saved as an event, in order. You can read those events as pages, or open a stream that replays them and then delivers new ones live. ## Pages or a stream | Call | Use it to | Order | | --- | --- | --- | | [List a conversation's events](/api-reference/events/list) | Load history, catch up, or poll | Oldest first | | [Stream a conversation's events](/api-reference/events/stream) | Show progress live | Saved events first, then live ones | The list returns `data` and `nextCursor`. Pass `nextCursor` back as `cursor` until it is `null`; more events can arrive later. ## Open the stream Send both headers and `Accept: text/event-stream`. `cursor=0` replays everything; a higher cursor replays only events after it. ```bash curl --fail-with-body -sSN \ "$FIN_BASE_URL/v1/users/$FIN_USER_ID/conversations/$FIN_CONVERSATION_ID/stream?cursor=0" \ -H "X-Api-Key: $FIN_API_KEY" -H "Authorization: Bearer $FIN_TOKEN" \ -H 'Accept: text/event-stream' ``` The browser's `EventSource` can't send these headers, so stream through your backend, which keeps the key and token. To show a conversation when it opens, read its history with the list and draw it once, then open the stream with the last event's `seq` as `cursor`. Replayed from `cursor=0`, saved events arrive a few at a time, and a view that draws each batch shows finished runs as if they were still working. ## Saved and live events ```text : connected id: 42 event: run.started data: {"delivery":"durable","seq":42,"payload":{"input":"Hello","runId":"…"}} event: agent.text_delta data: {"delivery":"live","payload":{"text":"Hello"}} ``` | `delivery` | Saved? | What to do | | --- | --- | --- | | `durable` | Yes. It has a `seq`, appears in history and replays on reconnect. | Apply it to your saved state. | | `live` | No. No `seq`, never replayed. | Show it, then replace it. | `agent.text_delta` carries the reply while the agent writes it. When the saved `agent.entry` arrives, replace the temporary text with it. Lines starting with `:` are comments and keep-alives; parse the SSE framing before reading `data` as JSON. ## Render a reply An assistant `agent.entry` may carry `interrupted: true`: the model's response was cut off. Mark that draft as interrupted while nothing follows it. When the same turn writes again after automatic recovery the later words answer in full, so draw them in the draft's place and leave the draft out of the final answer's Copy action. `transcriptEntries` and `threadTurns` do this, and also draw a long reply once when a later reply of its turn says the same thing again with only reads between them. The journal keeps every entry. The durable draft replaces its live deltas. A reply's `text` is markdown that reads well as it is. If you render markdown, you can draw more from it: | The reply writes | What it means | You can show | | --- | --- | --- | | A table with an asset's symbol alone in the first column | Figures for several assets or periods | A table with each asset's logo | | A signed figure: `+61.2%`, `−14.3%`, `+$18.08` | A change. Levels, rates and risk never carry a sign | Green for up, red for down, with the sign kept | | A bold symbol: `**SUI**` | An asset the reply names | The asset's logo beside it | | A link: `[DefiLlama](https://defillama.com/chain/Sui)` | The source of what the sentence says | The site's name and logo | | A fenced block whose info string is `next` | Up to three replies the user could send next, one per line | A button per line that sends it as the user's next message | The agent can ask for several tools in one step. Each `tool.call` carries `batch`: its `index` among the calls asked for together and their `size` (1 for a call asked for alone). They arrive together, in `index` order, and the agent reads every result before its next step, so you can draw them as one group rather than as a chain. A call made before this field existed has none. Up to four independent reads can run together. Their `tool.result` events arrive as those reads finish, which can differ from the calls' `batch.index` order. Match each result to its `callId`; keep `batch.index` for display order and `seq` for event replay. One failed or stopped read does not erase another read's completed result. Actions, approvals and questions wait for preceding reads, and no later inference starts until the current batch has finished or the run has stopped. The text never carries read times or a list of sources. Each `tool.result` names its provider (`source` or `sources`) and when it read it (`fetchedAt`), so you can show both, for example on a collapsed line in place of a card per tool. A `market_history` result gives each asset a `trendUsdDecimal` list of up to 24 prices, oldest first, for a trend line. You can also draw trades, automations, the wallet, orders, saved contacts, grids and research reads from the events and tool results themselves. Tell the agent which ones you draw with `context.renders` on each message ([Start a run](/api-reference/runs/start)), and it leaves those facts to you: a reply beside a card is one line, not a restatement of the card. Without it the agent sums each one up in a line or two, so an app that shows only text still has the facts. Also send `context.country` from your server's edge geolocation with every message; [Tokenized stocks](/concepts#tokenized-stocks) explains which countries can trade these assets and the operator flag required for purchases. These assets can only be sold, never withdrawn or sent. | `context.renders` | Draw it from | The reply leaves out | | --- | --- | --- | | `receipts` | `intents.settlement` events | What a trade spent and received | | `automations` | `automation_create` results, and the automation itself ([Get an automation](/api-reference/automations/get)) | Its schedule or trigger, whether it may trade without asking, and when it ends | | `balances` | `intents_balances` results | What the wallet holds and its worth | | `orders` | `intents_orders` results | Each order's price, fill and expiry | | `contacts` | `contacts_list` results with `status: "listed"` | Each contact's name, address and network | | `research` | `market_sentiment`, `market_derivatives`, `market_news`, `market_screen`, `macro_series` and `protocol_fundamentals` results | Their readings: the crowd's mood, funding and positioning, headlines, the day's movers, macro figures and a protocol's fundamentals | | `grids` | `grid_create` and `intents_grids` results | Each grid's levels, state, cycles and profit | A `contacts_list` result holds only the contacts you sent as `context.contacts` with that message. Skip a lookup made right before a payment's approval: the approval shows the address. Add `placement` to `context.renders` when you draw a read's card only where the reply puts it, instead of one card per read as each lands. The agent then writes each finding as soon as it has it and puts a line such as `[card r7k2q]` right after the sentence the card backs, at most three a turn; it says any figure from a read it doesn't place in words. The name is the read's call id through `replyCardName` from `@nearai/financial-agents-react/model` (or `@fin/contracts`), so `splitReplyCards(text)` splits a reply into its words and the names it places, and `threadTurns` draws a whole turn that way. Without `placement` the agent writes no card lines, and `MessageMarkdown` leaves any it finds out of the words it draws. Add `show` instead when you draw a read's card where the agent's `show_cards` call stands, as `threadTurns` does. A message that carries `show` offers the agent the `show_cards` tool (and nothing else does: an automation's run, a partner's run and a message without `show` never see it), and the agent writes no card lines. The call names up to three cards a turn by the same names, with an optional `focus` (the token ids, mints or symbols that matter inside them), and its result lists the names it `shown`. Only the result of a read that can draw a card carries a name. A call that names any card the agent cannot show is refused whole and shows nothing, the cards it could have shown included, with `unknown_card` (no completed result has that name), `no_card` (that result draws no card), `over_limit` (more than three in the turn) or `focus_outside` (a focus entry the named results do not contain). A reply whose last step holds only `show_cards` calls ends the run there when every one was accepted or the turn has words, refused or not: the words before the call are the answer, and the agent isn't asked again. Send `show` beside `placement` while your app still draws card lines from older turns; `show` takes precedence. Add `solana_sell_many` to `context.renders` when your app draws a multi-coin Solana sale's approval card and its outcome (two to six coins sold under one approval, then one transfer back; the `solana_sell_many` tool and `SolanaSellManyContract`). Only a run told so is offered that tool, so an app that cannot show its card never meets its approval; without it the agent proposes one `solana_sell` per coin. Add `deposit` to `context.renders` when your app lets the user add money in place from a `deposit_request` result. Only a run told so is offered that tool: the agent calls it when the agent wallet cannot pay for what the user asked (a buy, swap, send, funding or basket buy) or holds nothing yet, after one short sentence on what is missing, and then ends its turn. The result is what the request lacks, every figure read by the server from the wallet, never the agent's own arithmetic: `purpose` (the request in the user's words, one line without square brackets), `symbol`, `needed` (the whole amount), `held` (what the wallet holds of it on every chain) and `short` (the gap, always above zero), with an optional `smaller` (the same request at what the wallet already holds, for one button). It moves nothing and opens no approval: the user deposits through your own flow. Draw it where the call stands in the turn, as you would a saved rule: it asks something of the user. When the money lands, send a message that says so and asks the agent to carry on with the request; it reads the wallet again and proposes the request for approval as usual. Without `deposit` the agent says what is missing in words. Add `share` to `context.renders` when your app lets the user share an answer publicly. The agent then ends an answer that reports what it read (a market, the news, odds, yields, a comparison) with its share lines: a fenced block whose info string is `share` (`REPLY_SHARE_FENCE`), in the same message as the answer, holding up to three lines a stranger can read with only the question beside them. The first is the finding that answers the question (asked why something moved, the cause); the others, what backs it with its figures, such as a market and its odds or a vault and its rate. They never carry the user's own balances or amounts. `splitReplyNextSteps(text)` returns them as `shareLines` and leaves them out of the `body`, so they never show in the reply; check them as you would any model text before you post them. Without `share` the agent writes no such block. Name only what you really draw: the agent trusts the list for that message alone, and an approval is always yours to show whatever the list says. A suggested next step only sends a message: anything it leads to that moves money still arrives as `approval.opened`. Offer the steps of the latest reply only, while no run is going. If you don't render them, drop the block. While a reply is still streaming, its `next` block may be unfinished, so hide everything from its opening fence to the end. Older replies may use none of these forms. ## Reconnect without missing anything Remember the `seq` of the last saved event you applied. Reconnect with it in `Last-Event-ID` (or `?cursor=`, which the header overrides). Ignore saved events you already have, by conversation and `seq`. Live text never moves the cursor. A stream can end at any time, and that is normal: when Fin replaces a server, it ends that server's streams so they resume on another. Every stream opens with an SSE `retry:` field, the number of milliseconds to wait before reconnecting; a browser `EventSource` honours it by itself, and your own client should too. Reconnect the same way when the connection drops or a reconnect answers `5xx`: with backoff and `Last-Event-ID`, never giving up after one failure. On `429` wait for `Retry-After`. A stream needs a live session: when the session expires, create a new one and reconnect. Streams count against their own limit. ## After reconnecting, read the resources Events show what happened; resources show where things stand now. [Get a run](/api-reference/runs/get) returns a run's status, reply, `pendingApprovals` and `pendingQuestions`, so you don't need to rebuild them from events. For an `approval.opened` event, read [Get an approval](/api-reference/approvals/get). For `question.opened`, read [Get a question](/api-reference/questions/get) before enabling its answer controls. ## Approvals, questions and pauses `run.paused` means the run is waiting for an approval or a questionnaire response; `run.resumed` means it continued; `run.ended` is sent once, with the final status. When the status is `failed`, `failure.code` says why, including which budget or spend limit had no room for the run's next model request ([Budgets and limits](/concepts#budgets-and-limits)). `approval.decided` records an approval decision. For an audit trail, read the approval itself ([Get an approval](/api-reference/approvals/get)): it keeps the action's `fingerprint` and, for an approved money action, the wallet that signed it (`signedBy`). `approval.consumed` means the approval was used to start the action, not that the action succeeded: follow the run for the result. `run.steered` marks where the agent read a message the user sent the working run ([Steer a run](/api-reference/runs/steer)): draw the user's message there, with its `steerId` matching the run's `steers` entry. It arrives at the agent's next step, so it can follow tool results that finished after the user sent it. A message sent while the run waited on an approval arrives after that approval's `approval.decided` (a denial) and `run.resumed`; one the run ended before reading never gets a `run.steered`. `question.opened` contains the complete questionnaire and its deadline. `question.answered` records the submitted answers, with none for a question the user skipped, or a whole-card skip. `question.closed` records expiry or cancellation. These are durable events: replay them on reconnect, but use the question resource's current status and deadline to decide whether it can still be answered. Question answers never authorize an action. ## Money events Trade progress and settlement events are a signal to read the record again: the trade under [List trades](/api-reference/wallets/list-trades) (filter by `runId` or `conversationId`) or [Get a trade](/api-reference/wallets/get-trade). Direct wallet withdrawals, the user's own swaps and limit orders have no conversation; read them directly. Venue chat withdrawals use their original conversation's events below. See [Deposits, withdrawals and trades](/wallet-transfers). A perps order, cancellation, margin change or withdrawal whose `tool.result` was unconfirmed (Hyperliquid's or the provider's answer was lost) is resolved later by recovery, never sent again. When the final answer is known, one `perps.reconciled` event arrives in the same conversation, after that call's `tool.result` and usually after its run ended. Its `callId` names the call, `approvalId` its approval and `tool` the tool (`perps_order_place`, `perps_order_cancel`, `perps_margin_update` or `perps_withdraw`); `result` has the same shape the tool returns (`applied` or `rejected` for a margin change). Show it in place of the call's unconfirmed result, on the tool row and on its approval card. It is durable: replay it on reconnect, and keep it over a `tool.result` for the same call that arrives after it. A Polymarket funding has two stages, not one final swap receipt. A `prediction.funding` event updates the approved call's first-leg result and the bridge observations, even after the run ended. Its `callId` and `approvalId` identify the call and approval; `result` has the funding tool's submitted-result shape. Replace that call's displayed outcome with the newest event in journal order, and keep it over a later-arriving original `tool.result`. Replay these updates on reconnect. `delivered_to_bridge` means native Base USDC reached the bridge, not that pUSD funded the account. The bridge's transactions are reported separately from `attribution`, as the bridge reports them; their `txHash` is the bridge's own and names no Polygon transaction. `credited` (with `creditRaw` and `transactionHash`, a Polygon transaction) means this funding's pUSD arrived, reported only when Polygon shows exactly one finalized transfer of the delivered amount out of the bridge address after the funding was signed, whose receipt credits the user's Deposit Wallet; `unknown` names its `reason`. The funding call itself waits up to a minute for that credit, so its result is usually `credited` already. Each event also carries the wallet's live pUSD `balance`, which is the wallet's, not this funding's. Do not infer completion from matching amounts, times or a balance change, or a refund from bridge `FAILED`. See [Approve Polymarket funding](/wallet-transfers#approve-polymarket-funding) for consent and estimated-output semantics. A `prediction.withdrawal` event updates an approved Polymarket withdrawal's original `callId` and `approvalId`; `result` has the tool's submitted-result shape with `operationId`, `transfer`, `bridge` and `deposit` evidence. Apply the latest observation in journal order, including after the run ends, replay it on reconnect and retain it over a late original `tool.result`. Recovery only observes the original operation; an uncertain transfer is never resent. Only evidence changes append an event; a new polling timestamp alone does not. Unsigned pre-key refusals remain refused rather than becoming submitted observations. After a finalized source revert, or a confirmed source transfer and its linked final deposit receipt, there are no further recovery polls for that withdrawal. An outgoing pUSD receipt confirms only the source transfer. Bridge completion, matching amounts/times and wallet balance changes do not attribute arrival. Only the retained unique own-account deposit's final receipt does. Its arrival is the existing deposit ledger credit, never a second credit from this event. The approved loss limit checked the bridge estimate before transfer, not an on-chain or final-conversion minimum; bridge liquidity can hold, fail or reduce delivery. See [Approve Polymarket withdrawal](/wallet-transfers#approve-polymarket-withdrawal). A running Solana request also emits best-effort `solana.progress` snapshots. Join them by `operationId`, `approvalId` and the original `callId`; keep the highest `revision` for that operation. `phase` is `funding`, `swap` or `sweep`, with `state` describing only that phase. `preparing` and `prepared` precede dispatch, `submitting` and `pending` await confirmation, `uncertain` retains an unresolved attempt, and `not_executed` or `failed` describes that attempt rather than the entire request. Native attempts carry `transactionIndex`, which is never an Intents plan leg index. A multi-coin sale's (`solana_sell_many`) swaps name instead the `sale` they sell, its zero-based place in the approved `sells`, and its one sweep names neither. A sweep's `delivering` means Solana confirmed its transfer while 1Click delivery remains unconfirmed. `confirmed` funding means SOL arrived, not that a purchase completed; a confirmed swap can still need a sweep. Once a single-coin sale's swap lands, every later snapshot carries `paid`: what that swap sold, the same amount the final outcome reports as `paid`. Show it in place of an estimate while the sale finishes; until then, what a share of a holding sells is known only from a balance read before the approval. `refunded` funding or sweep reports only that phase's refund. Use `intents.settlement` for funding receipt precedence, and the final tool outcome or `solana.reconciled` for the operation's ending. Missing progress means unknown progress, not failure or permission to retry. Replay snapshots like other durable events, including after the model turn ends; observation uses no model inference. A Solana buy, sale or withdrawal whose `tool.result` was unconfirmed (a transaction whose landing was unknown, or a transfer back to the agent wallet that 1Click had not yet settled) is resolved the same way: one `solana.reconciled` event arrives in the same conversation, after that call's `tool.result`. It carries the same `callId`, `approvalId` and `operationId`, and a `result` in the shape the tool returns: `settled`, `partial`, `refunded` or `not_executed`, with its `solana` detail (what was paid and received, the SOL left in the account, and each transaction's signature, state and fee). Show it in place of the call's unconfirmed result, exactly as for `perps.reconciled`. A funding (`solana_fund`, or the funding step of a USDC buy) has no transaction of its own to reconcile: its late settlement arrives as an `intents.settlement` event, like any other leg. See [Solana trades](/wallet-transfers#approve-solana-trades-and-transfers). A `prediction.order` event updates the original Polymarket placement's `callId`, `approvalId` and `operationId`, including after cancellation or after the run ends. Replace its displayed result in journal order, as for funding. Open and partially matched orders are not settled; `matched` still awaits settlement evidence. A cancelled order can retain earlier fills whose settlement is not yet confirmed. An uncertain placement is observed, never automatically placed again. A retained owner cancellation request can be continued against that same order; this cannot create or replace an order. The [event catalog](/events) lists every event. --- # Deposits, withdrawals and trades Each user's agent has its own wallet. The user funds it with a deposit, the agent trades from it with the user's approval, the user can swap in it from your own screen, and the user takes money out with a withdrawal. Fin routes and settles transfers through NEAR Intents (1Click); your app needs no Intents account of its own. If your app already reads its users' accounts from 1Click, it can read the agent wallet the same way: see [read the wallet from 1Click yourself](#read-the-wallet-from-1click-yourself). ## Discover the wallet, networks and assets After [user provisioning and login](/quickstart), read: ```http GET /v1/users/{userId}/wallet GET /v1/users/{userId}/wallet/supported-assets GET /v1/users/{userId}/wallet/balances ``` `wallet` is `null` until the user [creates it](#create-the-agent-wallet) with a signature. An existing wallet can need a one-time ownership confirmation. When the wallet read returns `confirmation`, show the complete existing `wallet.intentsAccountId` and explain that the signature confirms that account without moving funds or granting trade permission. Have the registered wallet or passkey sign `confirmation.message` unchanged, then send its authorization to `POST /v1/users/{userId}/wallet/confirm`. Use the returned wallet only after verifying its ownership receipt against your independently pinned worker key and the connected owner. Before requesting a signature, parse the message and require purpose `wallet.confirm`, `walletId` and `requestKey` equal to the reviewed wallet id, and the exact request `{ walletId, intentsAccountId }` matching the displayed account, with no extra fields. Never substitute a spending request under a confirmation label. Cancellation leaves the wallet unchanged; read the wallet again for a fresh message before retrying. Ownership statements distinguish version 1 (owner-signed creation) from version 2 with `basis: owner_confirmation` (an existing imported account confirmed by its owner). Their signed domains are respectively `fin.wallet-ownership.v1\n` and `fin.wallet-ownership.v2\n`, followed by the exact canonical `statement` bytes. Both bind wallet, account, agent, owner and deployment audience. Version 2 does not prove that the key was generated inside an attested worker. A missing or invalid receipt never establishes ownership; do not trust a key supplied by the response in place of your own pin. Supported assets returns the current provider catalog. Use returned network and asset identifiers; do not build your own chain enum or infer an asset from its symbol. A catalog entry is not a promise that every amount or route has a quote. Execution validates a current signed quote. Supported assets and new deposit admission return `503` when the provider catalog is unavailable or malformed. A withdrawal or swap quote also returns `503` if its catalog lookup or provider quote request fails: 1Click did not answer, or asked us to slow down (then with `Retry-After`). These responses carry `reason: "provider_unavailable"` and `retryable: true`. Do not interpret those failures as an empty catalog, a zero fee, or permission to submit. When 1Click answers the quote by refusing it, usually an amount below what it routes or a pair it does not offer, the quote returns `400` with `reason: "quote_refused"`: asking again unchanged gets the same answer, so change the amount or the assets. Recover an interrupted deposit using the retained request key and exact terms first; an already-admitted deposit does not require a fresh catalog to return its original instructions. | Destination or source | `rail` | `network` | | --- | --- | --- | | Native blockchain | `chain` | Exact catalog network id | | Public Intents ledger | `intents` | `near-intents` | | Confidential Intents ledger | `intents` | `near-intents-confidential` | These two ledgers are distinct from the NEAR blockchain. The normal portfolio uses opaque Fin `assetId` values and native asset metadata, so you never parse protocol token ids. The wallet's `intentsAccountId` is its NEAR Intents account, for apps that read it from 1Click themselves. An explicit Intents deposit supplies the protocol information necessary for that advanced signing path. All amounts are decimal integer strings in atomic units. For six decimals, `"1000000"` is one token. Keep calculations in integer arithmetic; never round through a JavaScript number. ## Create the agent wallet A new user has no wallet. The user creates it once, with one signature, usually the first time they fund the agent. Read the wallet: ```http GET /v1/users/{userId}/wallet ``` Until it exists, `wallet` is `null` and `creation` holds the message to sign: ```json { "wallet": null, "creation": { "message": "Fin authorization v1\n…", "controllerId": "8f0c…", "expiresAt": "2026-09-24T15:04:05.000Z" } } ``` Have the user sign `creation.message` with the wallet they signed in with (see [supported wallets](/authentication) for how each one signs), then send the signature: ```http POST /v1/users/{userId}/wallet Content-Type: application/json { "authorization": { "controllerId": "8f0c…", "expiresAt": "2026-09-24T15:04:05.000Z", "signature": { "kind": "evm", "signature": "0x…" } } } ``` Send `controllerId` and `expiresAt` back exactly as you received them. The message is valid for about five minutes; after that, read the wallet again for a fresh one. Without a signature the call is refused with `403 signature_required`. Once the wallet exists, calling this again returns it unchanged. ### In the same signature as sign-in If you use wallet sign-in, the user can create the wallet with the signature that signs them in, and sign nothing more. Send `createWallet: true` to [Start wallet sign-in](/authentication). For a user with no wallet, the answer has `createsWallet: true` and its message both signs them in and creates their agent. Create the session with that signature, then, within the challenge's five minutes, send the same challenge id and signature here: ```http POST /v1/users/{userId}/wallet Content-Type: application/json { "signIn": { "challengeId": "3f2b…", "signature": { "kind": "evm", "signature": "0x…" } } } ``` Send either `signIn` or `authorization`, not both. A sign-in that wasn't an account-opening one is refused with `401`. Past the five minutes, use `creation` above instead. ### With a passkey the user just created Creating a passkey signs nothing, so a user who signs up with one would otherwise confirm twice: once to create it, once to sign. If your own login just created and verified the passkey, send `createWallet: true` when you [create the session](/authentication) with it. When the answer has `createsWallet: true`, send an empty body here from that session within 270 seconds: ```http POST /v1/users/{userId}/wallet Content-Type: application/json {} ``` Only the session that registered the passkey can do this, and only while the user has no wallet; any other session, or this one after the 270 seconds, gets `403 signature_required` and uses `creation` above. Where the user's wallet is set up through the Agent API, the passkey still signs that API's own setup steps. ### Set up an Agent API wallet The user's wallet can instead be an agent they own in the NEAR Intents Agent API: its key stays in the Agent API, and its NEAR Intents account is a `0x` address. This is opt-in: ask Fin to enable Agent API wallets for your partner, or first for a few of your users, once your integration reads the wallet account routes below. Until then nothing in this section applies to your users and no response ever carries a `0x` account; a user it is not enabled for never gets one. Once enabled, `agent_api_wallets` is on in the user's List a user's features. An Agent API wallet's balance is held by its `0x` account, so the older `intentsAccountId` field has no truthful value for it, and the routes that name a wallet by it (Get the agent wallet, Create the agent wallet, Confirm wallet ownership, Get a 1Click session, Get balances) refuse one with `409 wallet_account_unsupported`. Read every wallet instead with Get wallet account (`GET /v1/users/{userId}/wallet/account`), Get wallet account balances (`GET /v1/users/{userId}/wallet/account/balances`) and Open a wallet account session (`POST /v1/users/{userId}/wallet/account/sessions`). They answer the same bodies, with the account named by `intentsAccount`: ```json { "intentsAccount": { "id": "0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed", "kind": "evm" } } ``` `kind` is `near` for a Fin-held wallet (the same id as its `intentsAccountId`) and `evm` for an Agent API wallet. The older responses carry `intentsAccount` too, always `near`. To set one up, send the same `authorization` or `signIn` to Start wallet setup instead of Create the agent wallet: ```http POST /v1/users/{userId}/wallet/setup ``` The answer is `completed` with the wallet when it was created at once (the user's wallet is not one the Agent API can own, or your partner is not enabled), or the first step the user signs in their own wallet: ```json { "status": "signature_required", "step": { "setupId": "intent_…", "step": "agent_create", "expiresAt": "2026-09-24T15:09:05.000Z", "summary": "Create an agent wallet you own…", "intent": { "standard": "eip712", "payload": { … } }, "policy": { "maxSlippageBps": 300, "destinations": [ { "network": "near-intents-confidential", "address": "0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed" }, { "network": "eth", "address": "0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed" }, { "network": "hypercore", "address": "0x857cd3362740c16ce4c55af0b81a23aa9e5723db", "venue": "perps" } ] } }, "wallet": null } ``` Show `summary`, and tell the user what the wallet they create allows. `policy` says it in Fin's terms, so you can put it in your own words rather than parse `summary`: Fin's agent may sign swaps that pay back to the wallet losing at most `maxSlippageBps` of their value in total (fees, price and slippage together, by 1Click's own USD values; 300 is 3%), and payouts only to `destinations` (their own NEAR Intents account, on `near-intents-confidential`, the wallet they signed in with, and the agent's own venue accounts, each marked with its `venue`); nothing else. Fin lists the agent's own account on each venue the user can use when they create it (`perps` its Hyperliquid account, `prediction` the Polymarket bridge's deposit address for its Polymarket account, `solana` its Solana account), so funding those needs no second signature; a destination with `venue` funds the user's own account there, so describe it that way, not as a payout. A venue Fin could not name in time is left out and is allowed later by its venue (below). A `grant_issue` step carries `accessExpiresAt` instead: when the access the user gives Fin's agent ends, unless they renew it sooner. Either field is absent when Fin cannot state it for the step; show `summary` alone then. Before the user signs `agent_create`, the Agent API requires you to show its Owner Terms, OutLayer's terms and its risk notice, word for word: > This is an experimental, mainnet-only beta service. You may lose all assets you put in this > wallet, or lose access to them. Keep amounts small. and to keep evidence that the user accepted them (which user, each document's address and version, what notice they saw, when), in your own backend. `summary` ends with the notice; it does not replace showing the terms. Show the notice again before the user funds the wallet (any deposit to an `intentsAccount.kind` `evm` wallet). Fin does not record this acceptance for you, and the Agent API team supplies the two documents' addresses and versions. `grant_issue` and later steps need no new acceptance while the same versions are in force. Then have their wallet sign `intent.payload` unchanged, as `intent.standard` says: `nep366` a NEAR delegate action (`signDelegateActions`), `nep413` a NEAR message (`signMessage`, the nonce decoded from base64), `eip712` EVM typed data (`signTypedData`), `webauthn` a passkey assertion with the payload as its request options. Send the intent with the wallet's output added: ```http POST /v1/users/{userId}/wallet/setup/continue Content-Type: application/json { "setupId": "intent_…", "signature": { "standard": "eip712", "payload": { … }, "signature": "0x…" } } ``` The answer is the next step, signed and sent the same way: `grant_issue` (the user lets Fin's agent use the wallet for a year), then `completed` with the wallet, named by `intentsAccount`. `provider_unavailable` means a step is still landing: send the same request again. A step past its `expiresAt` answers a fresh step to sign. Before the year is up, Get wallet account carries `renewal`: have the user sign it, send it to Renew wallet access (`POST /v1/users/{userId}/wallet/access/renew`), and complete the `grant_issue` step it answers the same way. ### Allow a withdrawal destination An Agent API wallet pays out (withdrawals, sends and the funding of a perps, prediction-market or Solana account) only to addresses its user allowed; setup allows their own NEAR Intents account, the wallet they signed in with and the agent's own account on each venue they could use then. A payout to any other address is refused with `403 destination_not_allowed` before anything is signed. To allow one, send its network (a network `id` from List supported assets) and address: ```http POST /v1/users/{userId}/wallet/destinations Content-Type: application/json { "network": "eth", "address": "0x5AAEB6053F3E94C9b9A09f33669435E7Ef1BeAed" } ``` The answer is the `policy_update` step the user signs, exactly like a setup step: show its `summary` (its `policy` lists every address the wallet may pay once the user signs, the new one included), have their wallet sign it, and send it to Continue wallet setup, which answers `completed` once the address is allowed. An address already allowed answers `completed` at once. The address is allowed in the NEAR Intents Agent API's spelling of it (an EVM address lowercase, for one), so allowing either spelling allows both. An address that is not one on its network, or an account on the public `near-intents` ledger (an Agent API wallet pays NEAR Intents accounts on `near-intents-confidential` only), is refused with `400` and nothing is asked. The Agent API lets a wallet change what it allows only every few minutes: sooner, the request is refused with `429 policy_change_throttled` and `Retry-After` in seconds, and nothing is asked or signed; ask again once it has passed. Once Fin has disabled the wallet, Continue wallet setup refuses its pending `policy_update` or renewal `grant_issue` step with `403` before the signature reaches the Agent API, so nothing is allowed or granted. The agent's own venue accounts are allowed by naming the venue instead, so you never copy an address: `perps` (its Hyperliquid account), `prediction` (the Polymarket bridge's deposit address for its Polymarket account) or `solana` (its Solana account). ```http POST /v1/users/{userId}/wallet/destinations Content-Type: application/json { "venue": "perps" } ``` Fin names the exact address and chain that venue's funding pays and answers the same `policy_update` step (its `policy.destinations` shows the account, such as `hypercore` and the Hyperliquid address), opening the account first when it is new; opening moves no money. A venue the user cannot use is refused with `perps_disabled`, `prediction_disabled` or `solana_disabled`, and a Polymarket account still opening with `no_account`: ask again within a minute. Until the account is allowed, the agent's funding of that venue is refused before any approval opens, its refusal naming the venue, and a Solana buy the user pays in USDC (Prepare or Place a Solana trade) is refused with `403 destination_not_allowed` before they sign; allow it once, before the user's first funding or when that refusal arrives, and the funding can be asked for again. Two more refusals come with `403` before anything is signed: `agent_slippage_exceeded` when a swap, trade or transfer would lose more of its value than the wallet's owner allowed (fees, price and slippage together, by 1Click's USD values at the quote's minimum output; very small amounts lose more to fixed fees, so a larger amount or a smaller loss bound may pass) or its quote states no USD value. `agent_api_orders_unavailable` means an order needs wallet setup to enable limit orders, or its lifetime exceeds this wallet's 168-hour maximum: finish [wallet setup](#set-up-an-agent-api-wallet) or choose at most 168 hours before trying again. Native Agent API orders are funded when placed. A transfer the wallet has signed cannot be called back by freezing or disabling it: it stays valid until its own deadline (minutes for most, up to 96 hours for a payment into a 1Click deposit). ### Prove the wallet was created for this user The wallet carries `ownership`: the policy worker's signed statement that it created this wallet for the owner the user signed in as. Verify it in your own backend, against the worker public key you pin from your own configuration — never against the key the receipt names: ```json { "id": "0f0c…", "intentsAccountId": "8a88e3dd…6f5c", "status": "active", "provisionStatus": "ready", "ownership": { "statement": "{\"agentId\":\"…\",\"audience\":\"https://api.example.com\",\"intentsAccountId\":\"8a88e3dd…6f5c\",\"owner\":{…},\"v\":1,\"walletId\":\"0f0c…\"}", "signature": "…base64…", "workerPublicKey": "ed25519:…" }, "createdAt": "2026-09-24T15:04:05.000Z" } ``` For this version 1 creation receipt, the signature is Ed25519 by the worker's identity key over `"fin.wallet-ownership.v1\n" + statement` — the exact bytes `statement` carries. Version 2 confirmation receipts use the distinct version 2 domain described above, and an Agent API wallet's version 3 receipt (`basis: "agent_api"`, only on the wallet account routes) is signed over `"fin.wallet-ownership.v3\n" + statement` and names `intentsAccount` instead of `intentsAccountId`. `@fin/contracts` exports `walletOwnershipMessage(statement)` and `walletOwnershipStatementSchema` for this. Compare the parsed statement's `walletId`, account, `agentId` and `owner` with what you asked for, and its `audience` with your deployment; a receipt that names anything else is not yours. `ownership` is `null` for a wallet created before this field existed and where the worker answered no receipt, so treat `null` as unproven rather than as a failure. Pinning the key independently and verifying locally is what makes the statement evidence: versions 1 and 3 prove owner-signed creation, while version 2 proves owner confirmation. A pin alone does not prove hardware attestation; that additionally needs verified measurement evidence. No API response can vouch for itself. ## Open a perps account Perps is off by default. Your deployment must enable the `perps` feature flag for the user before opening an account; [List a user's features](/api-reference/users/list-features) says whether they have it. First [create the agent wallet](#create-the-agent-wallet); opening its separate Hyperliquid account requires no extra owner signature and moves no funds. With your API key and the user's Fin session, call [Open a perps account](/api-reference/perps/open-account) with a UUID `Idempotency-Key` generated once for this request. Send no request body: ```http POST /v1/users/{userId}/perps/account Idempotency-Key: 4f3c7d2e-9b1a-4c5d-8e6f-0a1b2c3d4e5f ``` The SDK equivalent is `user.perps.openAccount({ idempotencyKey })`. If the response is lost, repeat with the same key. An already-opened account keeps its address and creation time. Opening it yourself is optional: the agent's first deposit or opening order in chat opens it too. Read it later with [Get a perps account](/api-reference/perps/get-account): ```http GET /v1/users/{userId}/perps/account ``` The SDK equivalent is `user.perps.getAccount()`. Get returns 404 until the account is opened and remains available for existing accounts when the `perps` feature flag is off. Both operations return `PerpsAccount`, with a lowercase `0x` address, ISO `createdAt` and `state` read live from Hyperliquid: ```json { "address": "0x1234567890abcdef1234567890abcdef12345678", "createdAt": "2026-10-07T08:00:00.000Z", "state": { "status": "observed", "observedAt": "2026-10-07T08:01:00.000Z", "accountValueUsd": "0", "withdrawableUsd": "0", "marginUsedUsd": "12.25", "positionCount": 1, "positions": [ { "coin": "BTC", "size": "-0.001", "entryPriceUsd": "61250", "positionValueUsd": "61.2", "unrealizedPnlUsd": "0.05", "marginUsedUsd": "12.25", "liquidationPriceUsd": "72480.5", "leverage": 5, "marginMode": "cross" } ] } } ``` The USD fields are exact decimal strings, not atomic token amounts. Keep them as strings or use exact decimal arithmetic; do not convert them to JavaScript numbers. `positions` lists each open position, largest `positionValueUsd` first, up to 100; `positionCount` counts them all. `size` is signed in the coin (negative is short), and a null `entryPriceUsd` or `liquidationPriceUsd` means Hyperliquid reported none, not zero. `positionValueUsd` is the position's notional at the mark price, not money in the account: its unrealized PnL is already part of `accountValueUsd`, so to show what the user owns, count `accountValueUsd` alone and never add the positions to it. When reported, `fundingSinceOpenUsd` is the whole position's funding paid since open, in exact USD (positive paid, negative received). It is already reflected in the account; never add or subtract it again from `accountValueUsd`. If the live state cannot be read, the account still returns with `state: { status: "unavailable", reason: "…" }`. Show that state as unavailable, never as zero or proof that opening failed; the account's address and creation time remain usable. Venue reads have a three-second deadline and a 2 MiB response limit. Network failures, timeouts and non-success HTTP statuses produce `provider_unavailable`; malformed or oversized responses produce `invalid_response`. Neither reason invalidates the account. The agent loads `perps_account`, `perps_positions`, `perps_orders`, `perps_fills` and `perps_overview` with its perps capability pack in a run admitted with the feature enabled. These read only its own opened account, never an address supplied in chat, and return exact decimal strings with bounded lists and explicit truncation. A missing account asks the user or partner to open it. `perps_markets` reads Hyperliquid's public market list (coin, index, size precision, maximum leverage, whether it is isolated-only or strict isolated, prices and funding) in every run, feature or not, so exits can still be placed. There are no positions/orders/fills HTTP routes in this release; use the account API for identity and summary state, and the tools for those detailed reads. When starting each run, report [perps availability](/concepts#perps-availability) with the optional `context.perpsAllowed` field computed by your trusted server, not chosen by the browser. Admission saves that report with the opening message and updates the user's latest region observation only if its timestamp is strictly newer; equal timestamps keep the first committed value. An omitted field does not clear the latest saved observation. Unlike contacts, the field belongs to retry identity: changing, adding or omitting it under the same `Idempotency-Key` conflicts, while an unchanged retry returns the original run without refreshing the observation time. This report does not authorize spending, and the saved latest observation is not permission for a current interactive run. ### Approve perps funding and withdrawal Agent funding and withdrawals use approval cards in a conversation, not another wallet transfer endpoint. The model proposes `perps_fund` or `perps_withdraw` with an exact USDC `amountRaw` (six decimals) and an explicit `maxValueLossBps` integer from 0 to 300. For example, `{"amountRaw":"2000000","maxValueLossBps":100}` means 2 USDC with a 1% loss bound. A funding spends that amount from one USDC or USDT holding of the agent wallet that covers it alone (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR), any USDC before USDT, swapped into Hyperliquid's USDC in the same leg under the same bound: a user holding only USDT needs no swap first. The card names the debit as USDC or USDT, since the holding is chosen when it runs. Before a funding's card opens, Fin checks that one holding covers the amount and prices the route with a dry quote: a funding no single holding covers is refused naming each holding, and one whose loss bound is below what the route costs now is refused naming the cost and the least bound that passes, so the model can ask the user for terms that fit; no card opens for either. After the user approves, a step refused for a moment before anything was signed (the swap provider not answering, a quote that went stale) is tried again under the same approval, up to three times over about a minute, before the call reports a refusal. The card displays the direction, exact amount, loss bound and destination ownership; neither tool lets the model select a destination. Approve it using the card's issued authorization, the same [signed approval flow](/sdk-recipes#decide-an-approval) used by other financial requests. ### Pay a venue funding with a coin Where the user has it, a one-shot funding they ask for in chat (`perps_fund`, `prediction_fund`, `solana_fund`, or a `solana_buy` paid in dollars, and a funded order's funding) may pay from a coin of the agent wallet instead of one USDC or USDT holding: NEAR, ETH, BTC, SOL, XRP, DOGE, ZEC, SUI, ARB or LTC, never SOL for the Solana account. The approval's `input` and its contract's terms then carry `payWith`: ```json { "amountRaw": "25000000", "maxValueLossBps": 200, "payWith": { "tokenId": "nep141:wrap.near", "decimals": 24, "maxInputRaw": "10500000000000000000000000" } } ``` `amountRaw` stays the dollars the venue receives, and every floor is still in those dollars. `payWith.maxInputRaw` is the most of the coin the funding may spend: the dollars at the price when the card opened, plus 5%. The user's signature covers both, and Fin spends the dollars of exactly that coin at its own price when it runs, never a stablecoin instead; if the coin fell more than 5% in between, nothing moves and the call refuses (`spend_cap_reached`). The coin is the one the user named, or, when no stablecoin holding covers the funding and exactly one coin does, that coin: draw it on the card from `payWith`, at its own decimals. An approval without `payWith` reads exactly as before. A buy from a token's page (Prepare a Solana trade) refuses `payWith`, and no standing grant, withdrawal or basket of two or more positions ever carries it. For funding, supply `context.perpsAllowed: true` when starting the current run only after your region checks permit it, and enable the user's `perps` feature. Missing or false region evidence refuses funding before signing. Withdrawal is an exit and is never blocked by this flag or region permission. It pays the agent's own Intents account, requires at least 1.31 USDC and leaves a 1 USDC reserve of the account's spot USDC: Hyperliquid charges 1 USDC on every withdrawal, because each one pays a new 1Click deposit address. A lost transfer acknowledgement remains `uncertain` while the original quote is reconciled; do not ask the model to retry it. With the user's `cash_outs` feature on, "close it and bring the money home" is one approval: a `composite` contract whose first piece is the immediate reduce-only close and whose second is a `perps_freed_withdrawal`, `{ "withdrawal": { "upToRaw", "maxValueLossBps" } }`. That withdrawal has no amount of its own: it brings back only what the close freed, as the policy worker reads it from Hyperliquid, never more than `upToRaw`, to the agent's own Intents account, and nothing when the close fills nothing. It exists only inside such a composite. Polymarket's `prediction_freed_withdrawal`, `{ "withdrawal": { "upToRaw", "maxLossBps" } }`, is the same after an immediate sale. Show `upToRaw` as the most that can come back, never as the amount. A new Hyperliquid account starts in `default` mode, where funding lands in its perps balance; Fin switches it to unified mode, where all USDC sits in spot and backs margin, before its first withdrawal or order. Funding and withdrawal have settled on mainnet through this path; funding below about 21 USDC cannot pass the 3% loss-bound cap, because of 1Click's fixed fee. ### Approve perps orders The agent trades the account through approval cards too: `perps_order_place` for one exact order, `perps_order_cancel` for cancelling one resting order and `perps_margin_update` for adding or removing margin on one isolated position. Each call needs its own approval; there are no standing trading grants. For example, a market buy of 0.01 BTC at 5x isolated with a 65000 worst price: ```json { "coin": "BTC", "asset": 0, "side": "long", "size": "0.01", "leverage": 5, "marginMode": "isolated", "entry": { "price": "65000", "timeInForce": "Ioc", "reduceOnly": false }, "takeProfit": null, "stopLoss": null } ``` The model takes the coin, index and precision from `perps_markets` and asks the user for the leverage and the margin mode with it, `cross` (the position shares the account's margin) or `isolated` (only the margin set aside for it is at risk); it never assumes either. `marginMode` is present exactly when `leverage` is; an order approved before margin modes existed has none and was cross, so read its absence as cross. `Ioc` is a market order within its worst price, `Gtc` rests on the book and `Alo` rests only as a maker order. Take-profit and stop-loss are reduce-only market triggers with a worst fill price; with no entry they protect the existing position. Every order pays near.com's builder fee of 0.07% of its notional, shown on the card, on top of Hyperliquid's own fees. The first order also applies the account's one-time settings (unified mode and the builder fee approval), which move no money. An order may also carry Hyperliquid's trailing stop, a reduce-only market exit on the same size that follows the best mark price and fires once the mark reverses by the retracement: ```json "trailingStop": { "retracement": { "percent": "2" }, "activationPrice": "70000" } ``` The retracement is a percentage (`"2"` is 2%, above 0 and below 100, at most four decimal places) or a price distance (`{ "price": "1500" }`, under the same price rules as the other prices). With an `activationPrice` the stop starts tracking once the mark reaches it; with `null` it tracks from placement. It is placed right after the order, or alone on the existing position with no entry; a reduce-only entry can't carry one. The trailing stop itself pays no builder fee. Opening or adding to a position needs the user's `perps` feature and `context.perpsAllowed: true` on the current run; otherwise it refuses with scope `request` or `not_available_in_region`. Exits stay available everywhere: reduce-only orders, take-profit, stop-loss and trailing stop on the existing position, cancels and margin changes. An order whose numbers the market's live rules refuse (wrong index for the coin, too many size or price digits, leverage above the market's maximum, cross margin on a market `perps_markets` marks `onlyIsolated`) is refused with scope `order_invalid` before anything is signed. The operation records a `PerpsOrderOutcome`: `placed` with each placement's state (`filled`, `resting`, `triggered_pending` for a waiting exit, `triggered` for an exit whose trigger fired and became a market order, whose fill appears in the account's fills, `rejected`) and its order and client order ids (a trailing stop comes last, with no client order id), `rejected` with Hyperliquid's reason (a refused leverage stops the order before it is sent), `cancelled`, or `not_executed`. A lost answer leaves the operation `uncertain`, keeping every placement Hyperliquid did answer; the host reconciles the rest by client order id and never submits them again, so do not ask the model to retry. A trailing stop has no client order id: its own answer names its order, and without one the host settles it only when exactly one unclaimed order on the account matches its terms, otherwise it stays uncertain. While an order that set a market's margin mode is uncertain, an order with the other mode on that market is `rejected` with "Not sent: an earlier isolated margin order on this market is not confirmed yet" (or `cross`) and nothing is submitted, so the first order can only ever land under the mode it was approved with. ### Approve margin changes `perps_margin_update` moves USDC between the account and one isolated position: `add` lowers the position's liquidation risk, so the agent can rescue a position close to liquidation; `remove` frees margin it no longer needs and raises that risk. Its approval contract is `type: "perps_margin"`, one exact change signed once: ```json { "coin": "BTC", "asset": 0, "change": "add", "amount": "25.5" } ``` The amount is an exact USDC decimal string, greater than zero, with at most six decimal places and below a billion. It applies only to a position `perps_positions` shows as isolated, never to a cross position. A market `perps_markets` marks `strictIsolated` refuses every removal while the position is open, with scope `order_invalid` before anything is signed. A margin change opens no exposure and pays no builder fee, so neither the `perps` feature nor `context.perpsAllowed` gates it. Its `PerpsOrderOutcome` has no placements: `applied` when Hyperliquid applied it, `rejected` with Hyperliquid's reason, `not_executed`, or `uncertain` when the answer was lost. Fin sends one margin change per account at a time: one approved while another is still unanswered is `rejected` with "Not sent: another margin change on this account is not confirmed yet", and nothing is submitted. An uncertain change is reconciled from the account's own transactions (Hyperliquid can include it from a day before its signing time until about two days after) and never submitted again. It stays uncertain while another identical change already sent could own the transaction found; one that was never sent does not count. If Hyperliquid never applied it, it ends `rejected` with "Hyperliquid never applied it" about two days later. The final answer arrives as a `perps.reconciled` event for `perps_margin_update`. Do not ask the model to retry an uncertain change. ### Automate perps entries, exits and margin To open a position, reduce one or add margin when a condition holds later (funding rate, open interest, margin ratio, liquidation distance, unrealized PnL, daily change, a time), the user approves a `perps_automation` contract on an automation; see [Perps automations](/automations#perps-automations). Fixed take-profit, stop-loss and trailing stops, and an entry at a fixed price, stay native orders, as above. Opening a position or adding margin from an automation needs the `perps` feature and a `context.perpsAllowed: true` your server reported within the last 7 days. ## Open a prediction-market account Prediction-market trading is off by default. Your deployment must enable the `prediction` feature flag for the user before opening an account, and the deployment must hold Polymarket builder credentials; [List a user's features](/api-reference/users/list-features) says whether the user has it. First [create the agent wallet](#create-the-agent-wallet). The account is a Polymarket Deposit Wallet on Polygon, which holds the agent's pUSD (Polymarket USD, backed one to one by USDC) and positions; Fin holds the key that controls it. Opening needs no extra owner signature and moves no funds. Call [Open a prediction-market account](/api-reference/prediction/open-account) with a UUID `Idempotency-Key` generated once for this request. Send no request body: ```http POST /v1/users/{userId}/prediction/account Idempotency-Key: 6b1e2f4a-3c5d-4e7f-8a9b-0c1d2e3f4a5b ``` The SDK equivalent is `user.prediction.openAccount({ idempotencyKey })`. Opening takes two steps on Polygon, each paid by Polymarket's relayer: wallet deployment, then its trading approvals. Once the account is recorded, Fin continues both steps automatically, even if your app disconnects. Do not repeat Open to advance normal setup. Opening it yourself is optional: the agent's first funding or order starts it too, and that first attempt is refused until the account is ready, about a minute later. While `status` is `opening`, poll [Get a prediction-market account](/api-reference/prediction/get-account) a few seconds apart until it is `ready`; reads never submit a relayer request: ```http GET /v1/users/{userId}/prediction/account ``` The SDK equivalent is `user.prediction.getAccount()`. Get returns 404 until the account is opened and remains available when the flag is off. Both return `PredictionAccount`: ```json { "address": "0x94bf330955a0b957662feaf878de77bf25f76cd9", "signer": "0x0000000000000000000000000000000000000001", "status": "ready", "createdAt": "2026-10-17T08:00:00.000Z", "balance": { "status": "observed", "observedAt": "2026-10-17T08:01:00.000Z", "pusd": "0" }, "positions": { "status": "observed", "observedAt": "2026-10-17T08:01:00.000Z", "stale": false, "positions": [ { "assetId": "71321045679252212594626385532706912750332728571942532289631379312455583992563", "marketQuestion": "Fed cuts rates in December?", "outcome": "Yes", "sizeSharesDecimal": "40", "averagePriceUsdDecimal": "0.25", "currentPriceUsdDecimal": "0.5", "currentValueUsdDecimal": "20", "costUsdDecimal": "10", "unrealizedPnlUsdDecimal": "10", "redeemable": false } ], "truncated": false } } ``` `pusd` is an exact decimal string; keep it as a string. When Polygon cannot be read the account still returns, with `balance: { status: "unavailable", reason: "provider_unavailable" }`: show it as unavailable, never as zero. `positions` comes from Polymarket's data API: each open position, settled winners awaiting redemption included (`redeemable`), largest `currentValueUsdDecimal` first, up to 100, with `truncated: true` when the wallet holds more. Its figures are Polymarket's display values as exact decimals, not settlement evidence. `observedAt` is when Fin read them. While Polymarket rate-limits Fin, the account answers with the last positions it read within the past hour, marked `stale: true`, so `observedAt` can be minutes old: show them as last known with that time, and never size a sale (a Half or All shortcut) or set a maximum from them. With none that recent, `positions` is `unavailable`. What the account holds is its pUSD plus its positions' current value; when `positions` is `unavailable` or `truncated`, that sum would understate it, so show the account's value as unavailable rather than as its pUSD alone. After a lost Open response or `503 provider_unavailable`, read the account: if it exists, observe its progress; if Get returns 404, retry Open with the same key once the provider is available. Fin reconciles uncertain setup requests before retrying them, with at least five minutes between attempts. Disabling the user, agent wallet or prediction feature stops new setup effects. Re-enabling the user or feature lets setup continue; a disabled agent wallet remains stopped. An account that was ready under an older approval set can return `opening` during its fixed setup upgrade. Fin keeps the same account and first ready timestamp. Wait for `ready` before funding or placing an order; reads never send the upgrade themselves. The agent loads `prediction_account` and `prediction_positions` with its predictions capability pack in a run admitted with the flag on. They read only its own account, never an address supplied in chat. Positions come from Polymarket's data API as display figures, converted exactly from its JSON numbers; they are not settlement evidence. Order placement uses the signed flow below. Eligible resolved winning positions are redeemed automatically into pUSD in the same Polymarket account. A separate approved withdrawal returns pUSD to the agent wallet. ### Automatic redemption of resolved winnings Fin checks ready Polymarket accounts in the background and redeems eligible resolved winning positions into pUSD in the same Deposit Wallet. Your app does not submit a redemption request, ask the agent to redeem or collect another approval. Losses whose current value is zero are skipped. The `prediction` flag does not gate this exit; disabled users, disabled agent wallets and accounts that are not ready are excluded. Redemption is one atomic batch with temporary position-ledger permission: grant the pinned adapter permission, redeem, then revoke it. It cannot send winnings to another address. A relayer acknowledgement and the data API's position display are not proof of completion: Fin requires submission evidence followed by an on-chain zero remaining position balance. An unavailable balance is never treated as zero. Read `prediction.getAccount()` for live pUSD after redemption. Redemption itself is not an Intents credit or withdrawal; use the separate withdrawal approval below to transfer it back. ### Approve Polymarket funding OpenAPI document **12.2.0** adds the `prediction_fund` approval contract, `prediction_disabled` refusal reason, `route_unavailable` refusal scope and `prediction.funding` journal event. Regenerate closed-enum client types and support this approval card and event before enabling the feature for your users. No existing route or variant is removed. OpenAPI document **13.4.0** adds the `credited` attribution variant, named reasons for an `unknown` attribution and the Deposit Wallet's live `balance` on the funding's result and every `prediction.funding` event, as described below. Regenerate closed-enum client types; events recorded earlier still parse. Funding has two stages: Fin delivers native Base USDC from the agent wallet to the official Polymarket bridge, then the bridge converts it into pUSD on Polygon for that same user's ready Polymarket Deposit Wallet. The model cannot choose a recipient. Fin spends one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR) that alone covers the amount, native Base USDC first, and never splits the amount across holdings. Native Base USDC is transferred to the bridge as it is; any other holding is swapped through 1Click into native Base USDC. Fin chooses the holding when it freezes the plan, after approval, so the approval card cannot name it; the activity shows it once the plan is frozen. A funding the user approved to pay with a coin (`payWith`, [above](#pay-a-venue-funding-with-a-coin)) swaps the debit's dollars of that coin into native Base USDC instead. **Final pUSD is estimated, not guaranteed.** The approved loss bound covers only delivery of Base USDC to the bridge. The bridge can charge fees, delay or hold a transfer, and a failed bridge report does not guarantee a refund. Explain these risks before approval. Keep this internal until eligibility and applicable Polymarket terms have been checked. Confirm with Polymarket whether your custody and trading model needs additional permission; builder credentials do not override access restrictions. A chat run admitted with `prediction` enabled can discover `prediction_fund`. The tool takes an exact debit and an explicit maximum first-leg loss including first-leg fees; for example, 10 USDC with at most 0.5% loss on delivery to the bridge: ```json { "amountRaw": "10000000", "maxFirstLegLossBps": 50 } ``` `amountRaw` is a positive integer string at six decimals, never a floating-point number. `maxFirstLegLossBps` is an integer from 0 to 300 and has no default. It does not set a minimum pUSD amount. One USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC before USDT) must cover the whole amount on its own, or the funding is refused before its card opens, naming each holding, and the prediction account must already be `ready`. A `prediction_order_place` buy the account cannot pay for (its pUSD less what open orders hold) is likewise refused before its card, naming what it can spend; a funding credits a little less pUSD than it moves, since the bridge keeps a fee. Use the [normal signed approval flow](/sdk-recipes#decide-an-approval): render the exact stored terms, then submit the owner's exact-request signature when they approve. The `prediction_fund` contract binds the amount, first-leg loss bound and expiry, not the source holding, for one execution through the bridge to the user's own Polymarket wallet. The same JSON on another tool is not authorized. A saved prompt or automation cannot grant this consent. There is no separate funding HTTP route or second approval flow. The current flag, account readiness and provider route are checked again before dispatch. `prediction_disabled` means the flag is off; `no_account` means the account is absent or not ready; `evidence_unavailable` with scope `route_unavailable` means the supported route, bridge minimum or required evidence could not be satisfied. These refusals are not a request to change tokens, recipient or loss limits. After approval, distinguish the first-leg result from the bridge's progress. Delivery of Base USDC to the bridge does not mean the Polymarket account has received pUSD. An uncertain transfer must not be submitted again: observe the original operation instead. A bridge report, a matching amount or time, or a balance increase alone never attributes pUSD to this transfer. A bridge failure alone must not be shown as refunded. The tool's `submitted` result identifies the retained `operationId`; it is not a settlement claim. Its `firstLeg` distinguishes `pending`, `delivered_to_bridge`, `refunded` and `not_executed`. Render bridge observations separately from `attribution`, Fin's answer to whether this funding's pUSD arrived: - `credited` (`creditRaw`, `transactionHash`): the pUSD arrived. Fin reports it only when Polygon shows the bridge's conversion of the delivery: exactly one finalized transfer of the first leg's delivered amount of USDC.e out of the pinned bridge address after the first leg was signed, that no other funding of the user's could claim, in a transaction whose finalized canonical receipt credits the user's Deposit Wallet in pUSD. `transactionHash` is that Polygon transaction. Show it as this funding's receipt, for example "4.99 pUSD arrived in your Polymarket wallet". Once credited it stays credited. The funding call waits up to a minute for it, so its result is usually `credited` already. - `unknown` with a `reason`: `not_at_bridge` (step 1 has not delivered), `delivery_unmeasured` (no delivered figure to match), `bridge_not_read` (Polygon could not be read just now, or the result was rebuilt without reading it), `awaiting_bridge` (Polygon shows no conversion of the delivered amount yet), `credit_not_verified` (the one matching conversion shows no single pUSD credit to the wallet) or `ambiguous` (several conversions, or several of the user's open fundings, could match). Events recorded before revision 13.4.0 say `provider_reports_no_source_link`. Show the stage and that the pUSD has not been confirmed yet; do not promise an amount. The bridge's own rows (`bridge.observation.transactions`) are progress to show. Their `txHash` is the bridge's and names no Polygon transaction; a row's `credit` was recorded only before 2026-11-15 and is never written now. The tool's result and each `prediction.funding` event also carry `balance`, the Deposit Wallet's whole pUSD balance (`pusdRaw` at six decimals and `readAtMs`) or `unavailable`. It is the wallet's balance, never this funding's amount; it is absent only from older events and from a result rebuilt without a live read. Apply each newer [`prediction.funding` journal event](/concepts-journal) to that call's displayed result, including events arriving after the run ends. Do not let a late original `tool.result` overwrite a newer observation. Read `prediction.getAccount()` for the wallet's live pUSD balance at any other time; pUSD on Polygon is not credited to the agent's Intents holdings. Funding does not itself approve a trade. Automatic redemption keeps winnings in that Polymarket account until a separately approved withdrawal. ### Approve Polymarket withdrawal OpenAPI document **14.1.0** adds the `prediction_withdraw` approval contract and `prediction.withdrawal` journal event. Update closed-enum clients, event handling and approval rendering before offering it. Withdrawal uses the existing signed chat approval flow; there is no new `/v1` route or separate SDK withdrawal command. The agent proposes exactly an amount and loss limit, with no address: ```json { "amountRaw": "10000000", "maxLossBps": 50 } ``` This approves a debit of **10.000000 pUSD** from the user's own ready Polymarket Deposit Wallet, with a **50-basis-point pre-transfer estimate limit**. `amountRaw` is a positive integer string in six-decimal pUSD atomic units. `maxLossBps` is required, an integer from 0 to 300, with no default. The exact one-shot `prediction_withdraw` contract binds `withdrawal: { amountRaw, maxLossBps }` and `validUntil`. Another tool, changed terms or an automation cannot use that approval. The only destination is the same user's confidential Intents wallet. Fin creates a unique native Polygon USDC 1Click deposit address for that wallet. Fin independently verifies its live signed `FLEX_INPUT` quote against the pinned quote signer, exact native Polygon USDC identity, own confidential recipient and refund account, deposit minimum and send window. Polymarket's official conversion service pays native USDC on Polygon (chain 137) to that address; there is no Base hop or direct offramp call. Fin obtains the withdrawal mapping and quote itself, then signs only one exact pUSD transfer from the own Deposit Wallet to that mapping. Neither the model nor your app supplies a recipient. The returned confidential balance is **USDC on Polygon**, which Polymarket funding does not spend (it spends USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR); using returned Polygon USDC for it requires a separately approved wallet swap first. It is credited under 1Click's Omni id `nep141:pol-0x3c499c542cef5e3811e1192ce70d8cc03d5c3359.omdep.near`. A withdrawal before 2026-11-09 credited the legacy HOT id `nep245:v2_1.omni.hot.tg:137_qiStmoQJDQPTebaPjgx5VBxZv6L`, which 1Click retired that day (as it did every HOT id on BNB Chain, Polygon and Avalanche): such a balance stays in the portfolio and can be swapped, but List supported assets no longer names a retired id and no deposit is made in one. If 1Click will not make the deposit address (it no longer quotes the asset into the account), the withdrawal is refused `route_unsupported` with scope `route_unavailable` before any signature, and nothing moves. Waiting does not change that answer; show it as a route that is unavailable, not as an outage to retry. **The limit is not a guaranteed minimum received.** Before transfer, Fin requires the bridge's estimated Polygon USDC output to meet both the signed deposit minimum and `ceil(amountRaw × (10000 − maxLossBps) / 10000)`. For the example that floor is **9.950000 USDC**. This checks an estimate before sending pUSD; it is not enforced on chain or on the final conversion or Intents credit. Bridge liquidity, fees and conversion can delay, hold, fail or reduce delivery. A bridge failure is not proof of a refund. Keep these risks visible before the user signs. Withdrawal is an exit and remains available when `prediction` is off. It still requires an enabled owner, partner and wallet, a ready own Polymarket account and live execution authority. Switching the flag off neither approves a transfer nor cancels one already sent. The `submitted` result retains an `operationId` and separate `transfer`, `bridge` and `deposit` evidence. A confirmed outgoing pUSD transfer proves only that pUSD left for the bridge. A bridge completion report, matching amount/time or balance change does not prove arrival. Only the unique own-account deposit's final receipt establishes attributed arrival or refund. The receipt uses the existing wallet-deposit ledger credit once: do not add another balance credit from the withdrawal or treat external pUSD as Intents inventory. Apply each newer [`prediction.withdrawal` journal event](/concepts-journal) to the original call and approval, even after the run ends or after reconnect. Keep it over a late original `tool.result`. Pending, held, failed, reverted, refunded and uncertain observations are not interchangeable with completion. An uncertain signature or relayer submission is never replaced or resent; recovery only observes the retained operation. A refusal proven to precede signing stays refused; recovery does not turn it into `submitted`. A transfer hash identifies verified source evidence, not an unverified relayer candidate. Identical observations produce no new event, and polling stops after a finalized revert or a confirmed source transfer with its final linked deposit receipt. Do not use event frequency as a liveness signal. No funded withdrawal acceptance is claimed. Eligibility, applicable Polymarket terms and any permission required for your custody/trading model still need review. ### Approve Polymarket orders OpenAPI document **12.5.0** adds `prediction_order` consent, `prediction.order` journal events and the order read/cancel routes below. Update closed-enum clients and approval rendering before enabling placement. The agent places an order through the signed approval flow below; the user can also place one themselves from your screen ([Place a Polymarket order yourself](#place-a-polymarket-order-yourself)). The agent proposes `prediction_order_place` for one exact BUY or SELL. It gets the market's exact `marketId`, `marketQuestion`, outcome and `assetId` from `prediction_market` or `prediction_preview`; missing identity is not guessed. The policy worker checks those fields again against the venue. The request includes a `limitPriceUsdDecimal`, explicit `maxFeeUsdDecimal` and `maxSpendUsdDecimal`, and one quantity: | Order | Quantity | | --- | --- | | GTC/GTD BUY or SELL | `{ "kind": "shares", "sizeSharesDecimal": "10" }` | | Immediate FOK/FAK SELL | The same share quantity | | Immediate FOK/FAK BUY | `{ "kind": "budget", "amountUsdDecimal": "5" }`, before fees | These are quantity examples, not live orders. Prices, pUSD amounts and shares are exact decimal strings with at most six places; invalid tick or quantity precision is refused. For BUY the limit is the maximum price before fees; for SELL it is the minimum. An immediate BUY at a better price can receive more shares than the limit-price minimum. GTC remains open until filled or cancelled. GTD also needs `expiresAt` in Unix seconds, at least three minutes ahead; Polymarket normally expires it one minute before that time. Show the exact terms and these restrictions **before signing**: - Fin checks the current fee schedule and total spend. Polymarket's signed order does not include fees, so these are admission checks, not a signed cap against later changes. The fee checked is the most Polymarket's taker fee (`shares × rate × p(1 − p)`) can be at any fill price the order allows: for a budget N, `N × rate × (1 − tick)`. A `maxFeeUsdDecimal` or `maxSpendUsdDecimal` below it is refused before the agent's approval opens, naming the least each must be. - Order expiry is enforced by Polymarket, not included in the signed order. - A match can still fail settlement. Cancellation can race a fill and cannot reverse it. Approve the issued `prediction_order` authorization through the ordinary owner proof flow. A changed term needs a new approval. Missing or mismatched grant data must not show an approve control. No other standing grant places these orders: an automation places one only under its own `prediction_automation` contract, and only the exact order its firing sealed ([Polymarket automations](/automations#polymarket-automations)). The `prediction` flag and current account readiness gate placement, not later cancellation. ### Place a Polymarket order yourself OpenAPI document **13.6.0** adds these two routes. The user can place an order themselves, with no agent run or chat. Like a limit order it takes three calls: prepare it, have the user sign it, place it. The order is the same `PredictionOrderInput` the agent's tool takes, with the same quantity rules and restrictions as above. **1. Prepare it.** Send the exact order: ```http POST /v1/users/{userId}/prediction/orders/prepare Content-Type: application/json { "marketId": "562793", "assetId": "1132…", "marketQuestion": "Will …?", "outcome": "Yes", "side": "BUY", "limitPriceUsdDecimal": "0.62", "quantity": { "kind": "shares", "sizeSharesDecimal": "10" }, "orderType": "GTC", "maxFeeUsdDecimal": "0.1", "maxSpendUsdDecimal": "6.3" } ``` The answer carries `order`, the exact order to show and sign; `requestKey`, the id of this order; and `authorization`, the `message` the user signs, with `controllerId` and `expiresAt`. Nothing is reserved or placed. A user without the `prediction` flag gets `403 prediction_disabled`, and one whose Polymarket account has not finished opening gets `404 no_account`. A size finer than Polymarket's hundredths (shares or a budget with more than two decimals) gets `400 invalid_input`. **2. Have the user sign.** Show the order, then have them sign `authorization.message` with their wallet. The signature names this order alone, under its own purpose: it cannot place another order, or stand in for a swap, a withdrawal or a limit order. **3. Place it** before `authorization.expiresAt`, with `requestKey` as the `Idempotency-Key`: ```http POST /v1/users/{userId}/prediction/orders Idempotency-Key: Content-Type: application/json { "order": , "authorization": { "controllerId": "…", "expiresAt": "…", "signature": { … } } } ``` The answer is the order, as Get a prediction order reads it. The custody worker checks the order against the live market (its tick, its minimum size, whether it still takes orders, the current fee and the signed fee and spend caps) and the account's balance before it signs anything. An order it refuses answers `409 prediction_order_changed` and places nothing; prepare it again. For a Polymarket order rule its `detail` names the rule beside the scope, for example `it was refused (order_invalid: fee_exceeded)`; the rules are `fee_exceeded`, `spend_exceeded`, `size_invalid`, `tick_invalid`, `price_invalid`, `deadline_invalid`, `market_mismatch` and `market_closed`. The same request sent again, after a timeout say, answers the same order or the same refusal, never a second order. Another body under the same key answers `409 request_key_conflict`. An `uncertain` order may already exist at Polymarket: keep reading it rather than placing a replacement. ### Read or cancel a Polymarket order Use these ordinary user-authenticated routes, or the matching SDK methods: | Route | SDK method | | --- | --- | | `GET /v1/users/{userId}/prediction/orders` | `prediction.listOrders({ cursor?, limit? })` | | `GET /v1/users/{userId}/prediction/orders/{orderId}` | `prediction.getOrder(orderId)` | | `POST /v1/users/{userId}/prediction/orders/{orderId}/cancel` | `prediction.cancelOrder(orderId)` | The collection is `{ data, nextCursor }`; follow its opaque cursor for every page. Each resource is `{ id, order, observation }`. Use its Fin `id` as the route's `orderId`; the CLOB hash is `observation.venueOrderId`, not a route id. Unknown or foreign ids return 404. Cancellation has no request body, new spending approval or replacement order. Repeating it addresses the same order. Reads and cancellation work with placement disabled. `observation` separates matched/unmatched shares from trade settlement. Raw share and receipt-backed `settledCollateralRaw`/`settledFeeRaw` values use six decimals; missing receipt amounts are unknown, not zero. `live` and `partially_filled` are open, `matched` is not yet confirmed settlement, and `uncertain` means the order may exist. `cancelRequested` is a request, not proof that the venue cancelled. Even a cancelled order can have pending earlier fills. A terminal `FAILED` trade is not a settled fill. After an uncertain placement, keep reading this retained id; do not place a replacement. Fin never automatically resubmits it. A durable cancellation request can continue only against that same order after a restart. Apply later `prediction.order` journal events to the original tool and approval row, including after its run ends. Keep them over a late original `tool.result`. The agent's `prediction_orders` and stop-only `prediction_order_cancel` tools use the same ownership and recovery path. ## Open a Solana account Solana trading is off by default. Your deployment must enable the `solana` feature flag for the user before the agent can buy, fund or search tokens; selling, withdrawing and reading the account never depend on it, so turning it off strands nothing. [List a user's features](/api-reference/users/list-features) says whether the user has it. First [create the agent wallet](#create-the-agent-wallet). The account is a Solana address of its own, controlled by a key Fin holds and separate from the agent wallet: the agent buys and holds Solana tokens there, funded from the wallet's USDC or USDT and paid back to it as USDC when it sells. Opening needs no extra owner signature and moves no funds, and it is optional: the agent's first approved buy or funding opens the account itself. Call [Open a Solana account](/api-reference/solana/open-account) with a UUID `Idempotency-Key` generated once for this request. Send no request body: ```http POST /v1/users/{userId}/solana/account Idempotency-Key: 9d2c5b7e-1f3a-4c6d-8e0b-2a4c6e8f0a1b ``` The SDK equivalent is `user.solana.openAccount({ idempotencyKey })`. If the response is lost, repeat with the same key. An already-opened account keeps its address and creation time. Read it later with [Get a Solana account](/api-reference/solana/get-account): ```http GET /v1/users/{userId}/solana/account ``` The SDK equivalent is `user.solana.getAccount()`. Get returns 404 `no_account` until the account is opened and remains available when the flag is off. Both return `SolanaAccount`: its address, when it was opened and a live read of its SOL and recognized token balances. ```json { "address": "BAMgx3XPWrXkNUuQiVWUZU6eB2HQZdwz9HNnT4tpo8LG", "createdAt": "2026-10-23T12:00:00.000Z", "holdings": { "status": "observed", "observedAt": "2026-10-23T12:01:00.000Z", "sol": { "lamports": "3000000000", "reserveLamports": "2660240", "spendableLamports": "2997339760", "priceUsd": "103.36", "valueUsd": "310.08" }, "tokens": [ { "assetId": "asset_0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9", "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263", "symbol": "Bonk", "decimals": 5, "tokenProgram": "spl_token", "amountRaw": "10000000000", "priceUsd": "0.00002", "valueUsd": "2", "averageCostUsd": "0.0000185", "unrealizedPnlUsd": "0.15", "costBasisStatus": "complete" } ], "valueUsd": "312.08", "unpricedCount": 0 } } ``` Every amount is exact: `lamports` (SOL, nine decimals) and each token's `amountRaw` are integer strings in the asset's smallest unit, scaled by `decimals`, and the USD figures are decimal strings. Keep them as strings or use exact decimal arithmetic. The reserve is the SOL the account always keeps for rent and network fees, so it can still sell and withdraw; `spendableLamports` is what is above it. `tokens` includes canonical wrapped SOL, tokens the venue verifies without a suspicious flag whose decimals and token program match the mint on chain, and tokens this account has a confirmed landed buy of. A buy paid in SOL still establishes recognition, even when it cannot establish a USD cost basis. Recognition uses exact mint identities; a name, ticker, icon or price alone never qualifies a token, and an approval or unfinished trade is not a confirmed buy. Unrecognized receipts are omitted from `tokens`, `valueUsd` and `unpricedCount`. This omission does not remove their on-chain balances. A recognized token without a price remains listed and counts in `unpricedCount`; `valueUsd` leaves its value out rather than treating it as zero. `averageCostUsd` is what the agent's own settled buys paid per whole token, with each sale taking its share, and `unrealizedPnlUsd` is the gain or loss against today's price; `costBasisStatus` says how far to trust them (`complete`, `partial` or `unknown`) and must be shown beside them. If balances or the evidence needed to recognize a held mint cannot be read, the account still returns with `holdings: { status: "unavailable", reason }`: show it as unavailable, never as an empty account. Recognition filters current account reads; it does not rewrite settlement records or existing accounting observations. Future observations use the recognized inventory. The Solana account is not part of Get balances' total; [Get portfolio](#portfolio-and-its-history) counts it, unrecognized tokens left out. ### Find tokens and read them Solana tokens are named by their mint address, never by a ticker: many tokens share one. The token reads (search, lanes, one token and its chart) are in [Solana tokens](/solana-tokens). The agent reads the same shapes with `solana_token_search`, `solana_token`, `memecoins_top` and `solana_account`; the search and the lanes need the flag in the run, while `solana_token` and `solana_account` need none, so what the user holds stays readable. ### Approve Solana trades and transfers The agent buys, sells and moves money to and from the account through approval cards in a conversation, not another transfer endpoint. The model proposes one of four calls with exact terms, the card shows them, and approving signs them with the [signed approval flow](/sdk-recipes#decide-an-approval) used by other financial requests. Each call in a conversation needs its own approval. The same buy or sale can also come from your own token page, with the user's signature and no conversation; see [Trade a token from your own screen](/solana-tokens#trade-a-token-from-your-own-screen). A buy that names a token pins its mint, its decimals and its token program, and the call is checked against the chain before a card opens. For example, a buy of 50 USDC of BONK with an 8% loss bound: ```json { "token": { "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263", "decimals": 5, "tokenProgram": "spl_token" }, "pay": { "kind": "usdc", "amountRaw": "50000000" }, "maxValueLossBps": 800, "maxSolTopUpUsdcRaw": "1000000" } ``` | Tool | Terms | Rules | | --- | --- | --- | | `solana_buy` | `token`, `pay` (`{ kind: "usdc", amountRaw }` in six-decimal USDC or USDT, spent from one holding of either that covers it, any USDC first, or `{ kind: "sol", lamports }`), `maxValueLossBps`, `maxSolTopUpUsdcRaw` | Needs the `solana` feature. At least 5 USDC. An exact input only: buying an exact number of tokens is not supported. `maxValueLossBps` is 1 to 1500, the all-in loss from what is paid to what is received, fees and price impact included. `maxSolTopUpUsdcRaw` is `"0"` to `"1000000"` (1 USDC): the most extra USDC the funding may add to keep SOL in the account for network fees, added only while the account holds under 0.01 SOL; the card shows a Top-up line when it may. A token with a hard risk flag, no price or an unreadable mint is refused before the card opens | | `solana_sell` | `token`, `amount` (`{ kind: "fraction", bps }` of the holding, or `{ kind: "exact", amountRaw }`), `receive` (`"usdc"` or `"sol"`), `maxValueLossBps` | An exit, never behind the feature. Selling ends in USDC on NEAR unless `receive` is `"sol"`, which keeps the proceeds in the account | | `solana_fund` | `amountRaw` (six-decimal USDC or USDT), `maxValueLossBps` | Needs the `solana` feature. Moves USDC or USDT from one holding of the wallet that covers it, any USDC first, into the account as SOL. The loss bound is 0 to 300 | | `solana_withdraw` | `amount` (`{ kind: "exact", lamports }` or `{ kind: "all_spendable" }`), `receive` (`"usdc"` or `"sol"`), `maxValueLossBps` | An exit, never behind the feature. Moves SOL back to the wallet; the reserve stays. The loss bound is 0 to 300 | None of them accepts a destination: the account and the wallet are always the user's own. A refusal before anything is signed names its scope: `buy_too_small`, `reserve_required` (it would spend the reserve), `loss_bound_exceeded` (no route returned at least the approved minimum) or `token_blocked` (the token's own rules or its missing price keep it from trading). A buy needs three minutes of its grant left when it starts, to fund the account and swap, so its approval's `contract.validUntil` is four minutes past the approval's own `expiresAt` (the card's countdown): a buy approved at any moment before `expiresAt` starts with that window, and approving after it is refused as any lapsed approval is. A call whose grant still ran out before it started is refused `authority`, and its tool result's `hint` says when it was offered and approved. A refusal closes that attempt; a different amount or bound is a new request that needs a fresh approval. The result is a financial outcome with a `solana` detail: `settled`, `partial` (a buy that funded the account but never swapped, or a sale whose proceeds stayed there as SOL, with `solLeftLamports` saying how much, or a sale or withdrawal whose transfer back 1Click failed, which names no `solLeftLamports` because the SOL it took is with 1Click until it refunds it), `pending`, `refunded` or `not_executed`, and each transaction's signature, state and fee. A result that is still `pending` or unconfirmed is finished by Fin and never submitted again: a later `solana.reconciled` event carries the final answer (see [money events](/streaming#money-events)), and [List activity](#activity) shows the same ending as a `solana` item. ## See what the wallet can hold ```http GET /v1/users/{userId}/wallet/supported-assets GET /v1/users/{userId}/wallet/balances ``` Supported assets lists every asset and network you can deposit or withdraw, with the ids to use in requests. Use those ids; don't build your own list of chains or match assets by symbol. Balances returns what the wallet holds, with prices and USD values read live from the provider. Its top-level `totalUsdCents` continues to mean available wallet holdings. The required `portfolio` object is the account's value: the wallet, its open limit orders and order payouts on their way back: | Field | Meaning | | --- | --- | | `availableUsdCents` | The same available-wallet total, or null if any wallet asset is unpriced. | | `inOrdersUsdCents` | The funds resting in open limit orders, at current prices. Null if an order's report is missing, more than 10 minutes older than the wallet read, newer than it, or unpriced. | | `incomingUsdCents` | Order payouts on their way to the wallet: a filled order's output or a cancelled order's refund, at the amount the order provider reports, before any settlement fee. Zero when nothing is on its way. Once a payout completes it is part of `availableUsdCents` instead. | | `totalUsdCents` | The account's value: available plus in orders plus incoming. Null while any part is unknown. | | `pricedSubtotalUsdCents` | Only the wallet assets that have prices, even when the complete wallet total is null. Never an estimated portfolio total; null if its exact sum exceeds the supported cent-string range. | | `asOf`, `complete`, `reasons` | The wallet observation time, whether `totalUsdCents` is known, and why not when it isn't. | | `hasAssets` | True when the wallet holds a positive balance or an order holds or is paying back funds; false only when both are known empty; null when an order's funds are unknown. A zero dollar value alone is not an empty wallet. | Every amount is an exact integer-cent string or null. Preserve null as unavailable. Show the total as the headline, with available, in orders and on its way beneath it when they are not zero. An order counts until its payouts complete; then it adds nothing, because the wallet's own balance holds what it paid back. The total is unknown only while an order's part can't be told: | `reasons` value | What happened | | --- | --- | | `order_allocation_unknown` | An order's amounts aren't reported yet, including a funded order whose deposit the order provider hasn't seen yet, or the order read was truncated. | | `order_observation_stale` | An order holding funds wasn't read in the 10 minutes before the wallet was. | | `order_settlement_unreconciled` | An order's payout failed, or only some of its fills have been paid out, so what is still to come has no amount. | | `order_prices_unavailable` | An asset an order holds or pays back has no price. | | `orders_unavailable` | The orders couldn't be read. | An order that never started funding does not count, and neither does one that ended with nothing deposited and no refund reported. Until the order provider reports any other funded order's deposit, the total is unknown (`order_allocation_unknown`): the funding transfer may still be on its way, so the wallet read may or may not hold it. The current summary inspects at most 100 orders that may still hold funds, and 1,000 retained changes per order; exceeding either bound leaves the order value unknown instead of reporting a partial sum. Orders the order provider reports ended and paid out, and orders never funded that it saw no deposit for, don't count toward that bound. Computed values exceeding the 160-digit cent-string bound are null with `valuation_out_of_range`; they are never rounded, clamped or substituted with zero. This view covers wallet holdings and limit orders; positions in separate Earn and perps accounts are outside its scope. External deposits enter available holdings when observed in the wallet; pending external transfers are not added. `hasAssets === false` establishes a currently empty wallet and order view, not that the user never held funds. Preserve access to prior history for withdrawn accounts. Use [the portfolio's history](#portfolio-and-its-history) for historical performance. A transfer goes over one of two kinds of `rail`: | Where the money goes or comes from | `rail` | `network` | | --- | --- | --- | | A blockchain | `chain` | the network id from supported assets | | A public NEAR Intents account | `intents` | `near-intents` | | A confidential NEAR Intents account | `intents` | `near-intents-confidential` | The two Intents networks are ledgers, separate from the NEAR blockchain. ## Portfolio and its history [Get portfolio](/api-reference/portfolio/get) is what the agent owns across every account right now: the agent wallet, the funds in its open limit orders, its Solana, Polymarket and perps accounts, and money on its way between them. It gives the total, each account's value, and each holding with its amount, price, value, 24-hour change and average cost. Use it for every figure you show. Use [Get balances](#see-what-the-wallet-can-hold) for the amounts a deposit, withdrawal or swap can use: those come from the wallet's custodian. ```http GET /v1/users/{userId}/portfolio GET /v1/users/{userId}/portfolio/history?range=1W ``` Values are exact millionths of a US dollar as integer strings (`totalUsdMicros`, `valueUsdMicros`), and amounts are in the asset's smallest unit (`amountRaw`, with `decimals`). Each holding names its asset in `asset`, as [tokens and chains](/tokens-and-chains#assets-on-portfolio-rows) describes. - **`provisional`**: a figure includes changes after the account last agreed with its custodian (`confirmedThrough`), such as a difference one read saw and the next has not confirmed yet. Show the value and say it is unconfirmed; the next read confirms or corrects it. - **`excluded`**: holdings no price values. They are left out of the total and their `valueUsdMicros` is `null`. Say the total leaves them out; never show them as worth zero. Tokens Fin treats as spam are never listed at all. - **`price.status`**: `priced` is a recent market price, `carried` the last one up to 24 hours old, and `last_trade` what the user's own last trade paid, for an asset no market prices. Opening Get portfolio also asks Fin to read again any account last read more than two minutes ago. It does not wait for those reads; call it again a little later to see them. [Get portfolio history](/api-reference/portfolio/history) is the data for the value chart. Its last point is always Get portfolio's total. | `range` | Points | `step` | | --- | --- | --- | | `1D` (the default) | 288 | `5m` | | `1W` | 168 | `1h` | | `1M` | 180 | `4h` | | `3M` | 90 | `1d` | | `1Y` | 365 | `1d` | | `all` | up to 400, from the first activity | `1d`, or a few days once that is more than 400 days ago | Pass `step` (`5m`, `1h` or `1d`) for coarser points, such as `range=1M&step=1d` for 30 daily points. A step finer than the range keeps is refused with `400`: `5m` works only on `1D`, and `1h` on `1D`, `1W` and `1M`. Each point's `gainUsdMicros` is the gain from the range's first point: the change in value less money that came in plus money that went out. `summary` gives the range's change, money in, money out, gain, and `gainBps`, the gain as a share of the first value plus the money in. A deposit is money in, never gain. `marks` say where the line moved for a reason other than gain: `coverage_out` where a holding lost its price and left the total, `coverage_in` where one gained a price and joined it, and `unexplained` where a change no deposit, withdrawal or trade explains landed, such as a transfer sent to the wallet from outside your app. An unexplained change counts as money in or out. None of them counts as gain. ## Read the wallet from 1Click yourself If your app already signs its users in with 1Click and reads their balances, history and orders from 1Click, it can read the agent wallet with that same code instead of Get balances. Fin gives your backend a 1Click session for the agent wallet; your backend keeps it exactly as it keeps your users' own 1Click tokens, and talks to Fin again only when it expires. 1. When the user creates the wallet, store its `intentsAccountId` next to your own user: it is the agent's account, and the account its tokens sign in as. 2. Get the agent a session with the user's session token: ```http POST /v1/users/{userId}/wallet/sessions ``` ```json { "intentsAccountId": "8a88e3dd…6f5c", "accessToken": "eyJ…", "accessTokenExpiresAt": "2026-09-25T15:00:00.000Z", "refreshToken": "eyJ…", "refreshTokenExpiresAt": "2026-10-25T14:00:00.000Z" } ``` 3. Keep both tokens on your server or in HttpOnly cookies, never where page JavaScript can read them, and send the access token as `Authorization: Bearer` to 1Click's account endpoints, such as balances and history. 4. When the access token expires, exchange the refresh token for a new one at 1Click, the same refresh call you make for your own users. 1Click answers with a new access token only, so keep the refresh token you have. 5. When `refreshTokenExpiresAt` has passed, or 1Click refuses the refresh token, get a new session from Fin. That needs a live session token for the user: open one again as you do when it expires, and only while your own login still holds. 6. When the user signs out, delete the agent's tokens along with their other credentials. Every call creates a separate session, and Fin keeps no copy of it. A session can read the wallet and cancel its open orders but never move funds (see the [security model](/authentication#security-model)). Withdrawals, swaps, trades and deposits still go through this API. ## Deposit To show what a deposit would credit while the user picks an amount, [get a deposit quote](/api-reference/wallets/quote-deposit). It creates nothing: no deposit, no address, and nothing is reserved. ```http POST /v1/users/{userId}/wallet/deposits/quote Content-Type: application/json { "rail": "chain", "network": "eth", "assetId": "asset_…", "amountRaw": "10000000", "maxValueLossBps": 100 } ``` The answer says what the agent wallet would be credited now (`expectedCreditRaw`) and the least it will be within the loss limit (`minimumCreditRaw`), as of `quotedAt`. Send that minimum as the deposit's `minimumCreditRaw`. Create a deposit prices the deposit again when it issues the address, so quote again if the user waits. Each quote asks 1Click once, so don't send one on every keystroke. `provider_unavailable` also means 1Click can't price it within the loss limit right now. Generate a UUID for this deposit and keep it with the terms before you send anything. For example, to deposit ten units of a six-decimal asset and accept at most 1% loss: ```http POST /v1/users/{userId}/wallet/deposits Idempotency-Key: 5a0b3f7e-8c2d-4e11-9a6b-0f3c2d1e4b5a Content-Type: application/json { "terms": { "rail": "chain", "network": "eth", "assetId": "asset_…", "amountRaw": "10000000", "refundAddress": "0x…", "minimumCreditRaw": "9900000", "maxValueLossBps": 100 } } ``` Deposits need no signature. The answer is the deposit. Once `instruction` is filled in, the user sends exactly that asset and amount from their own wallet to `instruction.address`, including `instruction.memo` if there is one, before `instruction.sendBefore`. Each address is for this deposit only. Sending late, or the wrong asset, network or memo, can lose the deposit. If something goes wrong, the funds are refunded to `refundAddress`. The amount is the deposit's: if the user sends more, the agent wallet is credited the instructed amount and the rest goes back to `refundAddress`; if they send less, all of it goes back. The deposit's `receipt` says what happened: `depositedRaw` is what arrived, `creditedRaw` what the agent wallet received, `refundedRaw` what went back. While it's under way, `seenAt` is when Fin first saw the user's transfer (it's `null` until then), and `arrivedRaw` is what 1Click reported arriving while it confirmed it. Once credited, `value` is what the credit was worth in US dollars at the price Fin recorded with it: `usd`, `priceUsd` and `pricedAt`. Show these; never use them to decide anything about money. Poll [Get a deposit](/api-reference/wallets/get-deposit) to follow it: | `state` | Meaning | | --- | --- | | `preparing` | The address is being set up. | | `awaiting_deposit` | Waiting for the user's transfer. | | `processing` | The transfer arrived and is being credited, or what arrived beyond the instructed amount is on its way back. | | `credited` | Done: the funds are in the agent wallet. If more than the instructed amount arrived, `receipt.refundedRaw` says how much went back. | | `refunded` | The funds went back to `refundAddress`, as when less than the instructed amount arrived. | | `failed` | The deposit could not be set up; nothing was sent to it. | | `expired` | The deadline passed and no transfer was seen. Fin keeps checking, so a late transfer still shows up. | | `unknown` | Fin saw something it could not confirm yet. Keep checking; don't send again. | ### Deposit to an address When the user doesn't know the amount yet, such as when they withdraw from an exchange, create a deposit address instead. It takes one transfer of any amount, so send only the asset and the network the user sends on: ```http POST /v1/users/{userId}/wallet/deposit-addresses Idempotency-Key: 9c1e2f60-3b7a-4d58-8e0f-2a6b4c9d1e73 Content-Type: application/json { "network": "base", "assetId": "asset_…" } ``` The answer is the [deposit address](/api-reference/wallets/create-deposit-address). Once `instruction` is filled in, show the user: - `instruction.address`, and `instruction.memo` when it isn't `null`. The address takes one transfer of that asset on that network. A second transfer, another asset or another network can be lost. - `instruction.minimumDepositRaw`, the least the transfer must carry. Less isn't credited: it is refunded to the agent wallet. It is usually worth about 25 cents; on a network where 1Click bridges only more (a few dollars of bitcoin, say), it is that network's own minimum. - `instruction.sendBefore`, three days away. A transfer sent later may be refunded instead of credited. When 1Click won't make an address for the asset on that network, such as a network it doesn't quote right now or one whose minimum is more than a few dollars, creating it is refused with `400` and `reason: "quote_refused"`, and no address is issued. Asking again on the same network gets the same answer, so offer the user another network. There's no refund address to ask for: anything that can't be credited goes back to the agent wallet itself. Poll [Get a deposit address](/api-reference/wallets/get-deposit-address) while the address is on screen. Its `state` reads like a deposit's, plus `incomplete`: less than the minimum arrived. That transfer is refunded to the agent wallet, so tell the user not to top it up. The `receipt` says what arrived (`depositedRaw`), what was credited (`creditedRaw`) and what went back to the wallet (`refundedRaw`). `seenAt`, `arrivedRaw` and `value` read as they do on a deposit: when Fin first saw the transfer, what 1Click reported arriving while it confirmed it, and what the credit was worth. To show roughly what an amount that has arrived will credit, [get a deposit quote](/api-reference/wallets/quote-deposit) for `arrivedRaw`, and label it as an estimate. Both a credit and a refund are money the user put in, so [the portfolio's history](#portfolio-and-its-history) counts them as money in, never as gain. From the moment the user is expected to send, the address is also in [activity](#activity) as a `deposit_address`. When the user pastes the transaction hash from their exchange or wallet, [report it](/api-reference/wallets/report-deposit-transaction) so the transfer is found sooner: ```http POST /v1/users/{userId}/wallet/deposit-addresses/{depositAddressId}/transactions Content-Type: application/json { "transactionHash": "0x…" } ``` The answer is the deposit address as it stands. Reporting is optional, since the address is watched either way. A hash that isn't a transfer to this address is refused with `invalid_input`. ### Deposit limits Fin can cap how much a user's agent wallet may hold, per partner or per user. When a limit applies, [Get balances](/api-reference/wallets/balances) carries it: ```json "depositLimit": { "maxWalletValueCents": "20000", "availableCents": "15000" } ``` `availableCents` is how much more the user can deposit right now, in US cents: the limit less what the wallet is worth and the deposits still under way. Show it before the user picks an amount, and keep a deposit within it. `depositLimit` is `null` when no limit applies. Getting a deposit address checks the limit again, valuing the deposit at the current price. A deposit that would pass it is refused with `429` and reason `deposit_limit_exceeded`, nothing is recorded, and repeating the same request gets the same answer: read Get balances again and offer an amount within `availableCents`. A deposit address already issued keeps working when a limit changes, and since the agent wallet is credited at most the instructed amount, sending more than instructed cannot pass the limit either. A deposit address has no amount to check. Creating one is refused with `deposit_limit_exceeded` only when `availableCents` is already 0. Nothing caps what the user then sends to it, so a transfer can take the wallet past its limit. Show `availableCents` beside the address as how much fits. What arrives counts toward the limit once it is in the wallet, so the next deposit or address is checked with it. To deposit from a NEAR Intents account instead, use `rail: "intents"`. The instruction is then an Intents transfer (`instruction.kind: "intents_transfer"`) for the user's Intents wallet to sign and submit. ## Withdraw A withdrawal takes three calls: get a quote, have the user sign it, send it. Tokenized stocks cannot be withdrawn: quotes and withdrawals return `403 asset_not_withdrawable`; sell them first. **1. Get a quote.** Choose what to send and where: ```http POST /v1/users/{userId}/wallet/withdrawals/quote Content-Type: application/json { "assetId": "asset_…", "amountRaw": "1000000", "destination": { "rail": "chain", "network": "eth", "assetId": "asset_…", "address": "0x…" }, "maxValueLossBps": 250 } ``` The destination can be any supported address the user chooses; Fin never infers it. The quote answers: - `terms`: exactly what will happen, including `minimumReceivedRaw` (the least the recipient gets) and `maxFeeRaw` (the fee cap; `null` means the provider didn't disclose one, not that it is free); - `quotedReceivedRaw` and `quoteExpiresAt`: the current price and how long it holds; - `requestKey`: the id of this withdrawal; - `authorization`: the `message` the user signs, with `controllerId` and `expiresAt`. Nothing is reserved or sent yet. **2. Have the user sign.** Show the user the terms, then have them sign `authorization.message` with their wallet. The message contains the same terms. **3. Send it** before `authorization.expiresAt`, with `requestKey` as the `Idempotency-Key`: ```http POST /v1/users/{userId}/wallet/withdrawals Idempotency-Key: Content-Type: application/json { "terms": , "authorization": { "controllerId": "…", "expiresAt": "…", "signature": { … } } } ``` The answer is the withdrawal. A successful answer means Fin accepted it, not that the money arrived. Poll [Get a withdrawal](/api-reference/wallets/get-withdrawal): | `status` | Meaning | | --- | --- | | `pending` | Accepted, not started yet. | | `processing` | Being sent. | | `completed` | Paid out to the destination. | | `refunded` | The transfer failed on the way and the funds came back to the agent wallet. | | `failed` | Nothing left the wallet; `failureReason` says why. | | `denied`, `expired` | Refused, or the signature ran out, before it started. | | `uncertain` | Fin couldn't confirm the result yet. Keep checking; never send a replacement. | If sending answers `503 provider_unavailable` with `retryable: false`, nothing was sent and the signature can't be used again: get a new quote. With `retryable: true`, nothing was sent yet: send the same request again while the signature is still valid. A `failed` withdrawal's `failureReason` of `quote_expired` means the quote ran out before the provider took the transfer: nothing left the wallet, so get a new quote. A `refunded` receipt may carry `refundReason`, 1Click's own code for why (such as `NO_LIQUIDITY`); show it, but don't branch on it, since 1Click may add codes. `value` is what the debit was worth in US dollars when the withdrawal ran, at the price Fin checked its plan against; it's `null` before there's a plan. ### If a request times out Don't guess, and don't retry money with a new key. Look it up by the key you used: ```http GET /v1/users/{userId}/wallet/withdrawals?requestKey= GET /v1/users/{userId}/wallet/deposits?requestKey= ``` If it's there, follow it by id. If it isn't, send the same request again with the same key and body while its signature is valid. An interrupted withdrawal can later close with a terminal refusal when Fin confirms nothing was sent. Signature expiry alone does not prove that an earlier request had no effect: keep following any pending or uncertain original withdrawal, and require a confirmed no-payment outcome before starting a replacement from a new quote. A deposit address has no list: send the same request again with the same key, and you get the same address. ## Swap A swap trades one asset the agent wallet holds for another, from your own screen: the user picks the assets and the amount, and no agent run or chat is involved. What it buys stays in the agent wallet. Like a withdrawal it takes three calls: get a quote, have the user sign it, send it. A tokenized stock can be swapped this way too, where the user may trade it. Send the user's country with both calls, as `context: { "country": "GB" }`: your server resolves it from the request (your edge's geolocation), and it applies to that one request, so Fin keeps it nowhere. Without a country where tokenized stocks are offered, or for a buy when they are not enabled for the user, the quote and the swap return `403 asset_not_swappable`. Selling a holding never needs them enabled. A retry that finds its swap needs no country. **1. Get a quote.** Choose what to sell, how much, what to buy, and the most the swap may lose: ```http POST /v1/users/{userId}/wallet/swaps/quote Content-Type: application/json { "sellAssetId": "asset_…", "amountRaw": "1000000", "buyAssetId": "asset_…", "maxValueLossBps": 250 } ``` `sellAssetId` is an `assetId` from Get balances and `buyAssetId` an `id` from List supported assets. The quote answers: - `terms`: exactly what will happen, including `minimumReceivedRaw`, the least the agent wallet receives of the bought asset: the quote's own guaranteed amount at your loss limit; - `quotedReceivedRaw` and `quoteExpiresAt`: what it would receive at the current price, and how long that price holds; - `requestKey`: the id of this swap; - `authorization`: the `message` the user signs, with `controllerId` and `expiresAt`. Nothing is reserved or swapped yet. A wallet that no longer holds the amount, or an asset that cannot be quoted, answers `409 swap_changed`. **2. Have the user sign.** Show the user the terms, then have them sign `authorization.message` with their wallet. The message contains the same terms. **3. Send it** before `authorization.expiresAt`, with `requestKey` as the `Idempotency-Key`: ```http POST /v1/users/{userId}/wallet/swaps Idempotency-Key: Content-Type: application/json { "terms": , "authorization": { "controllerId": "…", "expiresAt": "…", "signature": { … } } } ``` The answer is the swap. Fin prices it again when it runs, and swaps only if the new price still gives at least `terms.minimumReceivedRaw` within the loss limit; otherwise nothing is swapped and the swap is `failed` with `failureReason: "quote_rejected"`: get a new quote. Poll [Get a swap](/api-reference/wallets/get-swap) until its `status` is final: | `status` | Meaning | | --- | --- | | `pending` | Accepted, not started yet. | | `processing` | Running, or waiting for the provider to confirm it. | | `completed` | The bought asset is in the agent wallet; `receipts` says how much arrived. | | `refunded` | The provider sent the sold asset back to the agent wallet. | | `failed` | Nothing was swapped; `failureReason` says why, in the same words as a withdrawal's. | | `denied`, `expired` | Refused, or the signature ran out, before it started. | | `uncertain` | Fin couldn't confirm the result yet. Keep checking; never send a replacement. | If a request times out, look it up by its key before anything else, as for a withdrawal: ```http GET /v1/users/{userId}/wallet/swaps?requestKey= ``` List swaps holds only the swaps the user made this way; the agent's own trades are below. Any retry keeps the same key and body. An interrupted preparation may later close with a terminal refusal when Fin confirms nothing was swapped. An expired signature alone never resolves a pending or uncertain swap; follow its original id before considering a replacement. Each receipt carries the swap's evidence for display: `intentHashes`, the NEAR Intents ids of the intents that settled it, to quote to support (no public explorer shows them: the agent wallet swaps on the confidential Intents ledger), and on a refund `refundReason`, 1Click's own code for why. The swap's `value` is what it sold was worth in US dollars when it ran. `failureReason: "quote_expired"` means the quote ran out before the provider took the swap; get a new quote. ## Earn vaults The agent wallet can deposit into the same curated yield vaults near.com's Earn page offers. [List earn vaults](/api-reference/wallets/list-earn-vaults) names each one, the yearly rate its provider states now and the user's position in it: ```http GET /v1/users/{userId}/wallet/earn-vaults ``` Each entry carries the vault share token's `assetId`, its `symbol`, `name` and `provider`, its total value locked (`tvlUsd`), and `rate`: `percent` as decimal text (`"5.4017"` is 5.4017%), `type` (`APY` or `APR`), `source` (`yield_xyz` for the Gauntlet vaults, `taler` for TLO) and `observedAt`. Fin reads each provider at most every five minutes. The rate is the provider's variable figure, not a promise: show it as the provider's current rate and name the source. `rate` is `null` when the provider could not be read just now; show no figure then, never an older one. `payment` names the asset a deposit pays with and a withdrawal returns: its `assetId`, `symbol` and `decimals`. A deposit is a swap from the vault's payment asset into its `assetId`, and a withdrawal is the swap back, with the calls above. Buying shares needs Earn enabled for the user; otherwise the quote answers `403 asset_not_swappable`. Selling shares never needs it. `position` is the user's own position in the vault, `null` while their records show no shares of it. It covers the time since their share balance was last zero: | Field | What it is | | --- | --- | | `sharesRaw` | The shares held now, in the share token's smallest unit, those set aside for a resting order included. | | `firstDepositAt` | When the share balance last rose from zero. | | `depositedRaw` | What buying the shares paid, fees included, in the smallest unit of `payment`. | | `withdrawnRaw` | What selling shares returned, in the smallest unit of `payment`. | | `costBasisStatus` | `complete` when trades in the payment asset explain every share held, `partial` when shares also moved another way. | What a position has earned is what its shares are worth in the payment asset now, plus `withdrawnRaw`, less `depositedRaw`; Fin states the facts and no price, so the worth uses the share and payment prices you show. The figure holds only while `costBasisStatus` is `complete`. Shares transferred in or out, or traded for another asset, make it `partial`: the amounts then do not say what the shares cost, so show no earned figure. A swap a moment old may not be in `position` yet, so compare `sharesRaw` with the wallet's balance of the share token before showing one. ## Trades Trades are made by the agent during a run, and each one needs the user's approval (see [the quickstart](/quickstart#when-you-turn-tools-on)) or an automation's pre-approved limits. A trade can also pay out: to the user's main wallet or to an exact address they approved. Its `request.actions` name the destination; `/wallet/withdrawals` lists only withdrawals the user started themselves. List a run's trades, then read one: ```http GET /v1/users/{userId}/wallet/trades?runId= GET /v1/users/{userId}/wallet/trades/{tradeId} ``` A trade shows what the agent asked for, who approved it and its `status`, with the plan it ran and each step's receipt as evidence. A run that finished, or an approval that was granted, doesn't prove a trade settled: read its `status`. Each planned leg's `actionIndex` names the action in `request.actions` it carries out. A leg that paid an address has `transferPayout`, as a withdrawal's receipt does: where the payout landed and its transaction ids, for a link to that chain's explorer. A swap's leg has no public transaction to link: the agent wallet swaps on the confidential Intents ledger. | `status` | Meaning | | --- | --- | | `pending` | Not started yet, usually waiting for the user's approval. | | `processing` | Running, or a swap it sent is waiting for the provider to confirm it. | | `completed` | Every swap settled, or there was nothing to swap (`outcome.status` is `no_trade`). | | `partial` | Some swaps settled and a later one did not. The settled swaps stand; when the later swap never started, `outcome.stopped` says which one and why; independent execution can name each unstarted action in `outcome.blocked`. | | `refunded` | The provider sent the funds back to the agent wallet. | | `failed` | Nothing was swapped; `failureReason` says why, in the same words as a withdrawal's. | | `denied`, `expired` | The user denied it, or its approval ran out, before it started. | | `uncertain` | Fin couldn't confirm the result yet. Keep checking; never ask the agent for a replacement. | Only a trade can be `partial`: a withdrawal is one transfer. An approved `execution.mode` of `ordered` runs complete actions in order. `parallel_independent` allows up to four complete independent payouts at once after the full request is checked and its funding reserved; each payout is claimed once. `dependency_graph` adds canonical predecessor rows for mixed branches, each released only after its required actions settle. These are dependencies between initially funded actions, without output-funded amount bindings or conditions over previous action results. A chat request's limits, the maximum preparation attempts and the dispatch window appear on the approval before signing. An automation's card shows its execution mode only when it is not `ordered`, and never its preparation attempts or dispatch window; they stay in the signed contract under Exact terms. A chat request's `dispatchWindowSeconds` is exactly 1200, counted from when its approval opened: the approval's fifteen minutes and five more to start, so the trade starts whenever the user approves it while the card is open. Any other value is refused before an approval opens; only an automation's contract may sign another window, up to 86,400 seconds. A trade approved while an earlier one still holds the agent wallet reads `processing` and waits for that one to settle, then runs; if its window ends first it ends `failed` with nothing sent. Let the user review safe unfinished branches after a trade closes and every submitted action has a conclusive result. Call `POST /v1/users/{userId}/wallet/trades/{tradeId}/remaining-proposal` with `{}` (SDK: `user.wallets.prepareRemainingTrade(tradeId)`) to keep the original loss limits, or send `{ "originalIndices": [1], "maxValueLossBps": "650" }` when the user explicitly selects that action and a 6.5% all-in loss limit. The SDK keeps call options second and takes this body third: `user.wallets.prepareRemainingTrade(tradeId, { idempotencyKey }, body)`. Generate a new UUID for each fresh review intent and reuse it with the same body after a lost response. The available limit is 0–1000 basis points, and a recovery override cannot be lower than the original limit. Fin never selects a higher limit automatically. The default for ordinary new proposals remains 250 basis points. The server excludes settled and unresolved original or recovery claims. A conclusively not-executed or finally refunded latest attempt can receive a new approved attempt bound to its immutable terminal proof. Its old claim and consumed allowance remain unchanged, and current funding is checked again. Exact-input actions retain the original raw debit and token identities; exact-output swaps retain the output target and may require a different input amount at current prices. Swap and owner-withdrawal reviews derive new price limits at current prices. A transfer payout keeps its frozen minimum unless a higher loss limit is explicitly chosen; any independently requested minimum receive amount stays enforced even then. Ambiguous mappings and exact-output payouts cannot be reviewed this way. Ordered and graph reviews include unfinished prerequisites and descendants of a selected failed action. A preceding action must have settled conclusively before it can be omitted. A refunded, not-executed or uncertain claimed prerequisite cannot be bypassed by selecting a descendant. Independent actions do not add preceding siblings to the selection. Always show the complete returned request, including any included prerequisites, for the fresh signature. The response contains `request`, `originalIndices` (zero-based original planned positions), `proposalId`, `fingerprint`, `expiresAt`, and `run`. Follow that run in the original conversation and show its fresh approval normally. Repeating an `Idempotency-Key` and body returns the original proposal and run, including after settlement; another body under that key gives `409 request_key_conflict`. A new key can request another review after the previous group closes, including when that group settled only some actions. Different terms conflict while a review is active or uncertain. An expired unused review or a closed unclaimed review can receive a new immutable generation; once a selected group and its run close conclusively, another eligible unfinished group can receive a new review, including a proven failed prior attempt. Concurrent renewal clicks return the same generation. An earlier retired review can no longer execute. The click itself does not approve it. Without a key, matching active or claimed selections retain the older replay behavior. Never reconstruct executable actions in your client or send a new model prompt to repeat the entire original trade. A `409 trade_not_recoverable` means the original state, a required predecessor or the available subset no longer permits this review. Reviews always target the original root trade. A recovery child cannot become another recovery source; use the original trade and original positions supplied with the prior review. A root with historical nested recovery metadata refuses further review until that history is reconciled. After later receipts resolve an originally uncertain result, read `GET /v1/users/{userId}/wallet/trades/{tradeId}/remaining-actions` (SDK: `user.wallets.getRemainingTradeActions(tradeId)`) for current verified candidates. This read neither creates a proposal nor authorizes execution. An empty list means no action currently has the required proof. Each leg carries `intentHashes`, the NEAR Intents ids of the intents that settled it, for support: they are on the confidential Intents ledger, which no public explorer shows. A refunded leg may carry `refundReason`, 1Click's own code for why; it is `null` when 1Click gave no code. Show both, and decide nothing on them. ## Limit orders A limit order sells an exact amount of one asset for another at no less than a limit price. It rests with the provider until it fills, expires or is cancelled, and can stay open long after it was placed. What it buys comes back to the agent wallet. An Agent API wallet places and funds the order natively, with no separate deposit transfer. Its maximum `expiresInHours` is **168** (seven days), not 720. Chat uses that maximum when the user gives no duration; Fin-held wallets keep their 720-hour maximum and default. New wallets allow limit orders. For an older wallet, call Start wallet setup with `{}`; it returns the owner's `policy_update` step when needed. Sign and continue that existing setup flow once before placing orders. A step with `policy.limitOrder: true` means: "Your agent can place limit orders at the market price or better. Proceeds stay in your account." The fin app provides **Allow limit orders** on Orders and beside the corresponding chat refusal to start this flow. Until setup completes, or for a longer lifetime, preparation and chat approval are refused with `403 agent_api_orders_unavailable`. An order never changes its signed lifetime to fit. The agent's policy permits no price worse than the market when it places the order; a better limit price is unrestricted. ### Place an order from your own screen The user can place an order themselves, with no agent run or chat. Like a swap it takes three calls: prepare it, have the user sign it, place it. **1. Prepare it.** Choose what to sell, how much, what to buy, the least it sells at and how long it rests: ```http POST /v1/users/{userId}/wallet/orders/prepare Content-Type: application/json { "sellAssetId": "asset_…", "amountRaw": "100000000", "buyAssetId": "asset_…", "limitPrice": "0.357142857143", "expiresInHours": 720 } ``` `limitPrice` is how much of the bought asset each one sold must fetch, as a plain decimal, and `expiresInHours` runs from 1 to 720. The answer carries: - `terms`: the order, plus `minimumReceivedRaw`, the least the whole order receives at its limit price, rounded up, in the bought asset's smallest unit. This is the floor the user signs: an order that would receive less is never placed; - `requestKey`: the id of this order; - `authorization`: the `message` the user signs, with `controllerId` and `expiresAt`. Nothing is reserved or placed yet. A wallet that no longer holds the amount, or an asset the catalog does not list, answers `409 order_changed`. Placing orders can be turned off for a user, which answers `403 limit_orders_disabled`; reading and cancelling their orders always work. A tokenized stock can be traded this way where the user may trade it: send `context: { "country": "GB" }` with both calls, as for a swap. Without a country where tokenized stocks are offered, or for a buy when they are not enabled for the user, both calls return `403 asset_not_tradable`. A retry that finds its order needs no country. **2. Have the user sign.** Show the user the terms, with `minimumReceivedRaw` as the least they receive, then have them sign `authorization.message` with their wallet. **3. Place it** before `authorization.expiresAt`, with `requestKey` as the `Idempotency-Key`: ```http POST /v1/users/{userId}/wallet/orders Idempotency-Key: Content-Type: application/json { "terms": , "authorization": { "controllerId": "…", "expiresAt": "…", "signature": { … } } } ``` The answer is the order. Fin creates it with the provider and funds it from the agent wallet while the signature lasts: a step that has not started by `authorization.expiresAt` never starts, and an order created but not yet funded is cancelled. A funding transfer already sent is followed to its outcome like any other order. Once the order rests, its `state` is `funded`; when nothing was placed, it is `abandoned` with a `failureReason`, and the user prepares and places a new one. Terms the wallet no longer fits when you place them answer `409 order_changed` and place nothing. If the request times out, send it again unchanged, or look the order up by its key: ```http GET /v1/users/{userId}/wallet/orders?requestKey= ``` Any retry keeps the original key and body. If preparation was interrupted, Fin may later mark the original order `abandoned` once it confirms nothing was placed. Signature expiry alone does not prove that an `unconfirmed` order is absent; keep observing the same order. ### Orders the agent places The agent places an order during a run, and each one needs its own signed approval. That approval's `contract` has `type: "limit_order"` and holds the exact order in `order`, where a trade's approval has `type: "near_intents_transfer"`, so check `type` before showing the terms. ### Follow and cancel an order ```http GET /v1/users/{userId}/wallet/orders GET /v1/users/{userId}/wallet/orders/{orderId} POST /v1/users/{userId}/wallet/orders/{orderId}/cancel ``` `state` follows funding (`prepared`, `creating`, `created`, `signing`, `funded`, `abandoned`), and `observation` holds the provider's latest view of fills and payout. `unconfirmed` means the provider's answer was lost: an order may exist, so never place a replacement. `failureReason` says why an `abandoned` order funded nothing; `expired` means the user's signature ran out before the order started. `conversationId` and `approvalId` name the chat the agent placed the order in and the card the user approved there, to link an order back to where it was asked for; both are `null` for an order the user placed themselves and for a grid's order. `grid` is `{ gridId, cell }` for an order a [grid](#grid-trading) placed, and `null` for an order placed on its own. `position` is the provider-reported allocation of this order, or `null` before a usable report. `restingInputRaw` is the input still open; canceled, expired and filled orders have zero resting input. `filledInputRaw` and `filledOutputRaw` are cumulative successful fills, not wallet cash. `refund.principalRaw` is the unallocated main-order input **before deductions**, not the net amount returned. Missing or contradictory evidence leaves the affected amount `null`. `fills` lists each fill 1Click reported, oldest first: what it sold (`inputRaw`) and bought (`outputRaw`), when 1Click says it happened (`filledAt`) and when Fin first saw it in a report (`reportedAt`). It's `null` whenever `position.filledInputRaw` is. `depositReportedAt` is when Fin first saw 1Click report the order's funds arrived, and `paidOutAt` when it first saw the order end with every payout complete. Fills and funds Fin saw before it kept these times read `null`. `value` is what the order sells was worth in US dollars when it was placed, at the market price Fin kept then; it's `null` when Fin kept none from just before the placement. A canceled order funded with 2,413 raw units and no fills therefore reports zero resting input and a refund principal of 2,413. Even if `refund.providerStatus` is `COMPLETED` and names a `txHash`, `reconciliation` remains `unreconciled`: net wallet receipts and actual fees are not available from that report. `withdrawals` similarly retains payout references without inventing cash amounts. Never add refund principal or cumulative fill output to wallet holdings, or deduct estimated fees as actual. Use the current wallet balance response for observed cash holdings; label affected historical values incomplete and omit unknown gains. To cancel from your own screen, show the button while `observation.cancelable` is true and call [Cancel a limit order](/api-reference/wallets/cancel-order). The user's session is enough: no approval or signature, because cancelling moves nothing out of the wallet. What filled stays filled, and 1Click refunds unfilled principal, subject to deductions. It answers the order with `cancelRequestedAt` set, which is not yet proof of a refund: read the order until the fill status is terminal. Cancellation can race a final fill and end `FILLED`. `isPayoutStatusFinal` includes failed payouts; `payoutStatus: "COMPLETED"` reports provider success but still does not establish an exact net refund amount. Asking again is safe. The recorded stop request continues after temporary credential/provider outages or service restarts. After a timeout or `503 provider_unavailable`, read the original order to check `cancelRequestedAt` and its current observation; neither an error nor the request timestamp proves cancellation failed or a refund completed. An order that already filled or expired answers `409 order_not_cancelable`. ## Grid trading A grid buys low and sells high across a price range the user chose, on its own, with no agent run per trade. Its `levels` are 2 to 20 strictly ascending prices of a `base` asset in a `quote` asset. Each pair of adjacent levels is a **cell**, and a cell has at most one limit order resting at a time: - a **buy** of `quantityPerCell` base at its low level, or - a **sell** of the same `quantityPerCell` base at its high level. When a cell's buy fills and its payout reaches the wallet, Fin places the cell's sell one level up; when the sell fills, it places the buy at the low level again. Each buy then sell is one **cycle**, which earns `quantityPerCell × (high − low)` in the quote asset before fees. The quantity is fixed: profits never compound. Fin re-arms cells itself, with no model and no run, under the one approval the user signed for the whole grid. ### How a grid is created Only in chat, and only where your deployment enabled the `grid_trading` feature for the user; it is off by default. The agent asks the user for the range, the number of levels and the quantity, then proposes the grid as an approval whose `contract` has `type: "grid"`, with the exact terms in `grid` and the time the grid ends in `validUntil`. The user approves it with their signature like any money approval (see [the quickstart](/quickstart#when-you-turn-tools-on)), and approving it creates the grid. The grid's `approvalId` and `conversationId` name that card and its chat. No route creates a grid; to change one, cancel it and approve a new one. A grid runs for 1 to 720 hours (30 days) after the approval's own expiry; at `validUntil` its orders are cancelled and it ends `expired`. A grid starts by buying, with the quote the wallet already holds; it never swaps. Each cell's first side is fixed in the terms as `cells[i].start`, from the price when the agent proposed it: cells below the price, and the one straddling it, start on `buy`; cells above it are `idle` and never place. At least one cell buys. Agent API wallets use native limit orders for every cell, including reads and cancellation. Their applied policy must allow limit orders before approval. Each cell lasts at most 168 hours, but the grid may still last 720 hours; Fin-held cells retain their 720-hour maximum. A native cell expiring unfilled at its own deadline before `validUntil` re-arms on the same side without counting toward the three-miss stall. Fill evidence is the Agent API's relay of 1Click. A cell's buy rests with 1Click as a sale of the quote: it sells the quote that `quantityPerCell` costs at the low level, rounded up, at a limit price rounded so that it always receives at least `quantityPerCell` and never pays more than the low level per unit of base. That quote stays locked in the order while it rests. ### Read a grid ```http GET /v1/users/{userId}/wallet/grids GET /v1/users/{userId}/wallet/grids/{gridId} ``` [List grids](/api-reference/wallets/list-grids) answers the user's grids, newest first, a page at a time; [Get a grid](/api-reference/wallets/get-grid) answers one: | Field | Meaning | | --- | --- | | `state` | Where the grid stands; see below. | | `stopReason` | Why it is stopping or ended: `cancelled`, `expired` or `grant_revoked`. `null` while it runs or is paused. | | `terms` | The exact terms the user approved. They never change. | | `validUntil`, `endedAt` | When the grid ends, and when it did. | | `cells` | Each cell, lowest first: its `low` and `high` levels, the `side` its next or current order is on, its `state`, the `order` resting or being placed now (`id`, `side`, `state`, `fillStatus`) or `null`, its `cycles` and `realizedQuoteRaw`. | | `cycles`, `realizedProfit` | Completed cycles across every cell, and what they earned in the quote asset, as `raw` and as an exact `decimal`. | | `heldBaseRaw` | The base the grid's filled buys hold for their sells. It stays in the wallet when the grid ends. | | `state` | Meaning | | --- | --- | | `active` | Cells place orders and re-arm as they fill. | | `paused` | No order rests and none is placed. | | `stopping` | It was cancelled; its resting orders are being cancelled. | | `stopped`, `expired`, `failed` | Final. The grid stays readable and takes no command. | A cell's `state` is `pending` while it waits to place, `placing` while its order is created and funded, `resting` once the order rests with 1Click, and `idle` when it places nothing. A partially filled order keeps resting: only a fill of the whole order, paid out to the wallet, turns the cell to its other side. An order that ends with nothing filled, cancelled or expired, is placed again on the same side; after three such endings in a row the cell is `stalled` and places no more. An order that ends partly filled, or in a way Fin cannot read, stalls its cell at once. The rest of the grid keeps running either way. Each cell's order is an ordinary limit order: [List limit orders](/api-reference/wallets/list-orders) and [Get a limit order](/api-reference/wallets/get-order) answer it with `grid: { gridId, cell }`, so an orders screen can mark it as managed by its grid. Cancelling one of them with Cancel a limit order doesn't stop the grid: while it is active, the cell places the same side again. Pause or cancel the grid instead. ### Pause, resume and cancel a grid ```http POST /v1/users/{userId}/wallet/grids/{gridId}/pause POST /v1/users/{userId}/wallet/grids/{gridId}/resume POST /v1/users/{userId}/wallet/grids/{gridId}/cancel ``` The user's session is enough for each, with no approval or signature, and each answers the grid. In chat the agent can do the same, each with an approval card. - **Pause** an `active` grid: its resting orders are cancelled and nothing is placed until it is resumed. What filled stays filled, and what the grid bought stays in the wallet. - **Resume** a `paused` grid: every cell places again on the side it was on, under the approval the user already signed. It needs at least an hour left before `validUntil`. - **Cancel** a grid that is `active` or `paused`: its approval is revoked at once, so nothing more is placed. The grid answers `stopping` while its resting orders are cancelled, then ends `stopped` with `cancelled`. Nothing is sold: what the grid bought stays in the agent wallet. Cancelling a grid the user already cancelled answers it again, so a repeat is safe. Pausing and cancelling are never turned off. | Status and `reason` | When | | --- | --- | | `409 grid_not_active` | Pausing a grid that is not `active`. | | `409 grid_not_paused` | Resuming a grid that is not `paused`, or with less than an hour left. | | `410 grid_ended` | The grid expired or failed, or, for pausing and resuming, was cancelled. It stays readable; a new grid needs the user's approval in chat. | | `403 grid_trading_disabled` | Resuming a grid while grid trading is off for the user. Pausing and cancelling still work. | ## Activity [List activity](/api-reference/activity/list) is the data for an activity screen: the agent's trades, from chat or from an automation's run, the swaps the user made with Swap tokens, the user's deposits, transfers to deposit addresses and withdrawals, and the changes made to automations, in one feed, newest first. ```http GET /v1/users/{userId}/activity?type=trade&type=swap&type=deposit&type=deposit_address&type=withdrawal ``` Each item has a `kind` and carries one object named after it: `trade`, `swap` (what Get a swap returns), `withdrawal` (what Get a withdrawal returns), `deposit` (what Get a deposit returns), `deposit_address` (what Get a deposit address returns, in `depositAddress`), `solana` (a buy, sale, funding or withdrawal through the agent's Solana account that the agent asked for), `solana_sell_many` (a sale of several Solana coins under one approval that the agent asked for: each coin as approved, how the sale stands, what each coin did once recorded (`sales`, each with its own swap transactions) and what the whole sale returned, in `solanaSellMany`, whose `transactions` are the sale's one transfer back), `solana_trade` (a buy or a sale the user placed themselves on the token's page: what Get a Solana trade returns, in `solanaTrade`) or `automation` (the automation's id, its name, and whether it was `created`, `paused`, `resumed` or `deleted`). Render by `kind`. `swap` is new in document version 8.20.0, `deposit_address` in 8.24.0, `solana` in 13.3.0, `solana_trade` in 15.4.0 and `solana_sell_many` in 16.3.0; until a client renders them, ask for the kinds it knows with `type`. A `solana` item has one `status` in a trade's words (`pending`, `processing`, `completed`, `partial`, `refunded`, `failed`, `denied`, `expired` or `uncertain`), the exact `request` the user approved, what it `paid` and `received`, `solLeftLamports` when a `partial` ending left SOL in the account, and each transaction's signature for an explorer; `uncertain` means the result is not confirmed yet, so keep reading rather than asking the agent for a replacement. A `deposit_address` shows what arrived in its `receipt`: what was credited, and anything below the minimum that went back into the agent wallet (`refundedRaw`), with `state` `incomplete` while that refund is under way. For a completed address deposit, show `creditedRaw` when credited or `refundedRaw` when refunded as the wallet inflow; `depositedRaw` is what was originally sent, before any fees. Edits remain in the private change journal and appear in the chat receipt and automation detail, not in `/v1` activity. The server excludes them before source limits and merged pagination, so visible counts and cursors stay consistent; no API reset is required. A `trade` carries its `request` and each leg's `actionIndex`, so a trade whose actions are all payouts (`withdraw_to_owner`, `withdraw_transfer`) can be shown as a send to its destination, whether a chat or an automation asked for it; each leg's `inputPriceUsd` and `outputPriceUsd` value it at the prices its plan was checked against. To show one item in full, read it from its own route by its `id`: Get a trade, Get a swap, Get a withdrawal, Get a deposit, Get a deposit address or Get a Solana trade. Repeat `type` to keep several kinds; omit it for all of them. `origin=conversation` or `origin=automation` keeps only the trades asked for in a chat or in an automation's run, and `automation` also keeps changes to automations; the user's own swaps, Solana trades, deposits, deposit addresses and withdrawals are left out. Pass `nextCursor` back as `cursor` with the same filters for older items. A deposit or a deposit address appears from the moment the user is expected to send to it. One that expired unpaid stays out of the feed, but List deposits or Get a deposit address still returns it. --- # Idea baskets # Idea baskets Idea baskets are limited to enabled partners. Check `users.listFeatures()` for `baskets` before showing them. The read routes and Link an order to a basket step answer `403 baskets_disabled` when it is off for the user. A session sees only its owner's baskets; another owner's basket id answers not found. ## Read the user's baskets - `GET /v1/users/{userId}/baskets` — `baskets.list({ limit?, cursor? })`, newest first. Pass `nextCursor` unchanged to read the next page; stop when it is null. Each basket carries its `unused` venue money and `unusedUnavailable` venues, so a list can total what is left on venues without reading every basket. - `GET /v1/users/{userId}/baskets/{basketId}` — `baskets.get(basketId)`, including positions, the idea's kill condition, the cash it keeps back (`cashKeptUsdc`), how many steps its one approval covers (`steps`), when the owner approved it (`approvedAt`), failed or skipped buying steps with each step's `label`, unused venue money, and `performance`. In chat, Fin reads the same lists and baskets with `basket_read`, from any of the user's conversations, so it can answer about, finish, link or delete a basket made in another chat. A draft can still be revised or bought only in the conversation that drafted it; elsewhere Fin drafts it again as a new basket. ## Performance The existing detail GET and `POST /v1/users/{userId}/baskets/{basketId}/links` responses carry a mandatory `performance` object on `Basket`. No performance route or SDK method is added. `baskets.list` and `BasketSummary` are unchanged and do not carry performance; read the detail when drawing it. ```ts import type { BasketPerformance, BasketPerformancePoint, BasketPerformancePosition, } from "@nearai/financial-agents-sdk"; const basket = await client.user(userId).baskets.get(basketId); const performance: BasketPerformance = basket.performance; ``` This illustrative JSON shows the complete `performance` shape, for a draft allocated entirely to one spot position. These example figures are not market data: ```json { "mode": "estimate", "asOf": "2026-11-16T12:00:00.000Z", "startAt": "2026-11-09T12:00:00.000Z", "endAt": "2026-11-16T12:00:00.000Z", "chartPeriod": "7d", "returnPctDecimal": "4.2", "points": [ { "at": "2026-11-09T12:00:00.000Z", "returnPctDecimal": "0" }, { "at": "2026-11-10T12:00:00.000Z", "returnPctDecimal": "0.5" }, { "at": "2026-11-11T12:00:00.000Z", "returnPctDecimal": "-0.8" }, { "at": "2026-11-12T12:00:00.000Z", "returnPctDecimal": "1.4" }, { "at": "2026-11-13T12:00:00.000Z", "returnPctDecimal": "0.9" }, { "at": "2026-11-14T12:00:00.000Z", "returnPctDecimal": "2.7" }, { "at": "2026-11-15T12:00:00.000Z", "returnPctDecimal": "3.3" }, { "at": "2026-11-16T12:00:00.000Z", "returnPctDecimal": "4.2" } ], "positions": [ { "index": 0, "returnPctDecimal": "4.2", "leverageDecimal": null, "source": "stored_token_closes" } ], "fundingIncluded": false, "feesIncluded": false } ``` All fields shown are required. `mode` is `"estimate"` or `"actual"`; `chartPeriod` is `"7d"` or `"since_bought"`. `asOf` is the observation time; `startAt` and `endAt` bound the reported period; an empty `points` array does not imply a measured curve exists. All timestamps, including point `at`, are ISO datetimes. `positions[].index` is the integer position index. The top-level and per-position `returnPctDecimal` may be null; point returns are always signed decimal strings. `leverageDecimal` is a decimal string for a perpetual's actual approved leverage, or null when not applicable. `fundingIncluded` and `feesIncluded` are required booleans: both false for draft estimates and both true for actual returns based on existing valuation. Returns use **percent units**: `"4.2"` means +4.2%, `"-1.8"` means −1.8%, and `"0"` means unchanged, not missing. Keep these values as decimal strings and use exact decimal arithmetic, not `Number` or `parseFloat`. The server computes the returns and points; do not manufacture performance in the browser. | Position / mode | `positions[].source` | Valuation evidence | | --- | --- | --- | | Draft NEAR Intents spot assets | `"stored_token_closes"` | Stored token closing prices | | Draft Hyperliquid perpetuals | `"hyperliquid_candles"` | Hyperliquid candles | | Draft Polymarket outcomes | `"polymarket_clob"` | The selected outcome's CLOB price history | | Bought holdings | `"basket_valuation"` | The basket's existing since-bought holding valuation | ### Drafts: if bought a week ago `mode: "estimate"` is a hypothetical seven-day return on the planned allocations, not a return the user earned. For each position the server computes `(priceAtTime / startPrice - 1) × 100`, reverses the sign for a short, and applies the perpetual's stored approved leverage. The basket return is the sum of each position return multiplied by its planned `weightBps / 10000`. Retained cash contributes zero; weights are not renormalized to remove cash. The current draft planner supports 1x perpetuals: do not copy a mockup's 2x label or invent leverage that the approved plan does not contain. The chart has eight daily points, including the start seven days ago and now, with `chartPeriod: "7d"`. Label it “Last 7 days” and “estimate, if bought a week ago”. Draft estimates exclude trading fees and funding; show those limitations, not a net-return claim. If any position lacks the full seven days of history, its return is null, the basket return is null, and `points` is empty. Keep every position, including the missing one: never drop it or recompute a flattering return from only the covered subset. Hide the aggregate performance band and chart, and label unavailable position returns “new”, not 0%. Show all positions (up to 12), including a Polymarket outcome's market name. ### Bought baskets: actual since bought `mode: "actual"` reports the basket's existing since-bought valuation return, `changeUsdc / costUsdc × 100`, rather than replaying the proposed allocation. For each holding with `priceSource: "market"`, its return is `holding.changeUsdc / holding.costUsdc × 100`; an unavailable or cost-only holding has a null return, rendered “—” rather than a draft's “new” chip. Actual positions use `source: "basket_valuation"`, not one of the draft historical-price providers. If any holding lacks a market-valued return, the aggregate return is null too: suppress the total and explain that not every position has a live price. Do not substitute cost for a market observation or drop that holding. When every holding is market-valued, the headline uses the basket's existing return exactly, not an average of the holding percentages. Actual returns inherit recorded settlement costs and attributed funding: `feesIncluded` and `fundingIncluded` are true. This does not mean every future fee or funding payment is known; do not present it as a guaranteed final net return. The valuation and shared-holdings limitations below still apply. Actual `chartPeriod` is always `"since_bought"`; `startAt` is `boughtAt`, and `endAt` and `asOf` are the current valuation read time. Actual `points` is always empty: show an available return as a number only, with no chart. The response does not include per-basket historical valuation observations. No historical funding or cost curve is reconstructed from today's holdings, and no seven-day price-provider reads are made for actual returns. Do not infer observations from the period metadata. Honor nulls and empty points for bought baskets too; never substitute an estimate or a fabricated line. A share's Amounts-off setting hides dollar amounts, not return percentages or the performance disclosures. ## Delete a basket `DELETE /v1/users/{userId}/baskets/{basketId}` — `baskets.delete(basketId)` removes a draft or a bought basket from the user's ideas and answers `204`; the lists and reads then answer as if it never existed (another delete answers `404`). It moves nothing: what the basket bought stays in the user's accounts, and unused venue money stays on the venue to withdraw, so say so before the user confirms. It is refused with `409 basket_buying` while the basket is buying and `409 basket_awaiting_approval` while an approval to buy it is still open; decline that approval first. A deleted draft cannot be revised or bought. Delete is not gated by the `baskets` feature, so a user can always remove their own basket. In chat, Fin does the same with `basket_delete`, at once and without an approval card. Drafting and buying happen in chat. Buying asks for one approval of the exact venue trades, not permission to trade an idea indefinitely. Use the existing approval issuance and signing flow; sign the message Fin returns. A partial purchase does not roll back trades that succeeded. Offer the indicated withdrawal tool for unused venue money through chat, with a new approval; a read never withdraws anything. A draft is a plan: its budget can be more than the agent wallet holds. The draft's `walletShortfallUsdc` says how much more USDC the wallet needed when it was drafted, so the user has a target; it is absent when the wallet held enough. Buying reads the wallet again and refuses, before any approval, with the exact amount still missing. A step can itself fill only some trades. Such a basket is `partly_bought`, even if no whole step completed; inspect its positions and individual step results before proposing another purchase. ## Finish a partly bought basket A partly bought basket is never bought again as a whole. In chat, when the user asks to finish it, Fin proposes (`basket_finish`) the Hyperliquid and Polymarket orders that did not buy, at today's prices for the amounts the user approved, paid from money already on those venues: nothing more comes from the wallet, and a funding or spot step is not bought again. The proposal is a basket of its own with the ordinary draft card; buying it is one more approval of exactly those orders, whose signed contract's `walletDebit` is empty. Each order that buys then stands in for its step in the original basket (`linked: "finished"` on its holding), and the finishing purchase does not appear in the ideas list. If the venue money does not cover the orders, the proposal is refused; the user can move more there or link orders of their own. ## Link an order to a step that did not buy When the user buys what a failed step would have bought with an order of their own (in chat, each with its own approval, or on a venue page), link that order to the step so the basket shows and values it in the step's place: - Each entry of `failures` lists `linkable` orders: orders the user placed since the basket's result, for the step's market or outcome and side (for perps also its leverage and margin mode), that received something and that no basket step holds yet. Show them with the step, and an empty list as nothing to link yet. A funding step never offers one. - `POST /v1/users/{userId}/baskets/{basketId}/links` — `baskets.link(basketId, { piece, operationId })` links one of them and answers the basket. The step leaves `failures`; its holding gets `linked: "linked"`, its quantity and cost from that order's own fill, and a value like any other holding. When every step that did not buy is linked, the basket is `bought`. - It moves nothing and needs no approval. A link is permanent: repeating the same link answers the basket again; another order for a linked step is refused with `409 basket_step_linked`, a step that bought (or a basket that is not partly bought) with `409 basket_step_not_failed`, and an order the step does not offer with `400 basket_order_not_linkable`. In chat, Fin does the same with `basket_link` when the user asks to update the basket with orders they placed. The 40% concentration limit counts each instrument across all actions and buying steps; splitting a purchase into several steps does not raise that limit. ## Values are estimates Quantities come from each buying step's recorded settlement, not the proposed allocation or the account's current balance. Cost is what that step paid in USDC. Intents assets use the wallet's current prices. Perpetuals (`side` `long` or `short`, both 1x isolated) use the current mark and funding: the position's since-open funding is attributed by size to the basket's fill, and a short is worth its margin plus the fall in price since entry. A position on the other side of the same coin is not the basket's, so its value reads null. This attribution is an estimate, especially after other trades change the same position. Polymarket positions are shown **at cost** (`priceSource: "cost"`) until their price source has been reviewed. Values and changes are exact decimal strings in USDC, truncated toward zero to six decimal places at the response boundary. A null value means unavailable, not zero. Totals include only unused venue money attributable to this basket's recorded funding, after its order costs, fees and reservations, capped by the current spendable venue balance. Pre-existing cash and money from other baskets are not counted. If `unusedUnavailable` names a venue, its balance or attributable unused amount could not be established: do not show that as zero or imply no money was left there. Offer to review that venue account and withdraw through chat. A retained unused amount can be an estimate while the venue is unavailable; the overall value remains null until the missing amount can be priced. Hyperliquid unified accounts use their spendable spot USDC, not the perps-only withdrawable field. ## Shared holdings Assets, perpetual positions and outcome tokens are fungible across the owner's account. This page values what the basket bought, even if the user later buys or sells the same asset elsewhere. Show a shared-holdings disclaimer and the `alsoHeldOutside` note when the account's holding differs from the basket's quantity. The basket record is not a separately held or reserved portfolio. --- # Solana tokens Anyone can create a Solana token with any name, so a ticker names many tokens: dozens share `WIF`. These reads find a token by ticker, name or mint address, rank what is moving, and give Fin's verdict on any token, read from the token's own mint, so a person always chooses by mint and sees the risk before a buy. They draw on Jupiter's token data and the Solana network. The agent's own token tools (`solana_token_search`, `solana_token`, `memecoins_top`, `solana_token_history`) answer these same shapes. Discovery combines sampled provider feeds with positive meme-category evidence; it does not claim to enumerate every token on Solana. Explicit non-meme tags (DeFi, stablecoins, liquid staking, stocks and similar categories) take precedence over a broad meme-category match. A launchpad protocol token does not become a meme because its platform creates memes, and names or ticker matches never establish membership. Every route takes your API key and the user's Fin session. Search, lists and a list's price lines and launch status also need the `solana` feature enabled for that user, and answer `403 solana_disabled` without it; check [List a user's features](/api-reference/users/list-features) first and leave a memecoin list out of your app for a user without it. One token's detail and its chart need no feature, so a token a user holds stays readable and sellable while buying is off. A `503 provider_unavailable` means a data source did not answer: read again shortly. It never stands for an empty list, a price of zero or a safe token. A catalog list can instead retain a previous snapshot with explicit stale or partial source coverage. None of these routes moves money or needs a signature. To let the user buy or sell from a token's page, see [Trade a token from your own screen](#trade-a-token-from-your-own-screen); for the trades the agent proposes in chat, see [Approve Solana trades and transfers](/wallet-transfers#approve-solana-trades-and-transfers). ## Recognized account holdings [Get a Solana account](/api-reference/solana/get-account), Open a Solana account and the `solana_account` tool return the same current inventory: native SOL, canonical wrapped SOL, venue-verified tokens without a suspicious flag whose decimals and token program match the mint on chain, and tokens this account has a confirmed landed buy of. A token bought with SOL remains recognized even without a USD cost basis or a current price. Approval alone or an unfinished trade does not establish a buy. Names, ticker symbols, icons and quoted prices never establish identity or recognition. Other incoming tokens are omitted from `holdings.tokens`, its total `valueUsd` and `unpricedCount`. A recognized token without a price remains listed and counts as unpriced. If missing or invalid metadata or purchase evidence leaves recognition unresolved, `holdings` is `unavailable`; this does not mean an empty account. Recognition changes current inventory reads, not on-chain ownership, trade authorization or existing accounting records. Get portfolio and Get portfolio history value only recognized tokens: an unrecognized one is named in `excluded` and never counts as gain or as money in or out, and a change in recognition restates the history rather than drawing a move. Unresolved recognition never falls back to a full inventory. See [opening a Solana account](/wallet-transfers#open-a-solana-account) for exact amount handling and [the portfolio and its history](/wallet-transfers#portfolio-and-its-history) for how the account counts toward the total. ## Find a token Call [Search Solana tokens](/api-reference/solana/search-tokens) with what the person typed: ```http GET /v1/solana/tokens/search?query=wif ``` The SDK equivalent is `user.solana.searchTokens({ query: "wif" })`. `query` is a ticker, a name or a pasted mint address, and a leading `$` is ignored. The answer is up to ten candidates, best match first. A pasted mint answers that token alone, and resolves even when Jupiter does not list it yet. ```json { "query": "wif", "ambiguous": true, "source": { "name": "Jupiter", "observedAt": "2026-10-23T12:00:00.000Z" }, "items": [ { "mint": "EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm", "symbol": "WIF", "name": "dogwifhat", "decimals": 6, "tokenProgram": "spl_token", "priceUsd": "0.1969389134882048", "liquidityUsd": "5812345.67", "verified": true, "stats": { "1h": { "volumeUsd": "120400.5", "traders": 512, "priceChangePct": "1.5" } }, "risk": { "level": "low", "hard": [], "soft": [] }, "tradable": true } ] } ``` `ambiguous` is true when another candidate shares the top candidate's symbol. Then the query does not name one token: show the candidates, each with its mint shortened to its first and last four characters beside its symbol, name, liquidity and age, and let the person choose by mint. Never pick a token by its symbol, its name or its icon: look-alikes copy all three. A candidate whose `tradable` is false is for reading only. A symbol or name is text the data source supplied: Fin cleans it of markup, links and control characters, but it is still not yours to trust as an instruction or an identity. ## Read one token [Get a Solana token](/api-reference/solana/get-token) answers one token by the mint address you got from a search, or from the user's holdings: ```http GET /v1/solana/tokens/{mint} ``` The SDK equivalent is `user.solana.getToken(mint)`. It answers a search candidate's fields (price, liquidity, market capitalization, age, launchpad, the risk verdict and trading activity over 5 minutes, 1 hour, 6 hours and 24 hours: volume with its buying and selling sides, the part judged organic, traders and the price change, each present only where the data source has it). It adds the fully diluted value, the number of holders, the share of the supply its largest holders hold (`topHoldersPct`) and its creator holds (`creatorHoldsPct`), and the data source's organic score from 0 to 100 (`organicScore`), each also present only where the data source states it. It answers 404 for an address that is no token. `decimals` and `tokenProgram` are read from the mint on chain, and they are the values a buy or a sale names, so copy them exactly. `iconUrl` is present when the data source lists an icon for the token (see [Draw a token's icon](#draw-a-tokens-icon)); draw a placeholder when it is absent. `links` carries the token's own `website`, `x` profile and `telegram`, each present only where the listing names one that reads as what it claims: https, no credentials or port, an X profile rather than a post, and a site that is not a link shortener, a launchpad or a trading terminal. The site loses its query and fragment. The links are the token creator's claims, not Fin's: open them in a new tab and never treat them as a sign the token is genuine. Fin's agent never reads them. `membership` distinguishes a confirmed `meme`, a `launch_candidate` whose category is not confirmed, `other`, and `unknown`. Its `basis` names the classification evidence; the token's symbol or name is never enough. `firstPoolAt` is the first pool's opening time, `createdAt` is mint creation when known, and `discoveredAt` is when Fin first recorded it. Do not substitute one for another. `marketObservedAt` and `assessmentObservedAt` date the market facts and mint read. `research` reports `ready`, `limited` or `unavailable`, the available activity windows and missing evidence. These describe support for research claims, not a probability of gain or a safety grade. Show `dataGaps` and absent figures explicitly. A young token can have useful current activity while lacking history for a daily trend. Transaction counts (`buys`, `sells`) are not distinct wallets (`buyers`, `sellers`, `traders`); `organicBuyers` is the venue's organic net-buyer count. `netBuyers` counts all wallets whose buys exceeded their sells; it is not buyers minus sellers. Both counts are nonnegative, following [Jupiter's definitions](https://developers.jup.ag/blog/what-is-organic-score). Missing values never become zero. ## Read a token's holders [Get a token's holders](/api-reference/solana/get-token-holders) reads a token's ten largest holders from the chain: ```http GET /v1/solana/tokens/{mint}/holders ``` The SDK equivalent is `user.solana.getTokenHolders(mint)`. An `observed` answer lists each owner once, with all its accounts added up, largest first: its `amountRaw`, its `sharePct` of the mint's `supplyRaw` (cut to two decimals, so a tiny holder reads `0.00`), `kind` and `creator`. `kind` is `program` when no key signs for the owner, such as a pool, a vault or a launchpad's bonding curve, so its balance is not one person's; `creator` is true for the wallet the data source says created the token. A `program` holder Fin recognizes also names its `venue`: `pump_fun` for pump.fun's bonding curve, `launchlab` for Raydium LaunchLab's, and `pumpswap`, `meteora`, `raydium` or `orca` for that venue's pools. The field is absent for any other holder, so a `program` holder without one is still a pool or a vault Fin has no name for. Shares are of the whole supply, so they need not match `topHoldersPct`, which is the data source's own summary. `holderChange` lists how much the number of wallets holding the token changed, as a percent per window (`1h`, `6h`, `24h`): `{ "window": "6h", "pct": "-1.5" }` is down 1.5% in six hours. It is a percent the data source states, never a count of wallets, and `null` when it states none. An answer is kept for a minute. When the chain cannot be read the route still answers 200 with `status: "unavailable"` and `reason: "rpc_unavailable"`; keep showing the token and try again later. `unreadable_mint` means the mint's account holds no supply Fin can read. An address that is no token answers 404. It needs no feature flag. ## Fin's risk verdict Every token carries a `risk`: its `level` (`blocked`, `high`, `medium`, `low` or `unknown`) and the flags behind it. It comes from one function over the token's mint and the data source's report, so a search, a list and a detail read agree. | Flag | Kind | What it means for a holder | | --- | --- | --- | | `freeze_authority` | hard | The creator can freeze holdings, so a holder may not be able to sell | | `transfer_hook` | hard | Every transfer runs a program the creator chose | | `permanent_delegate` | hard | Someone can move or burn tokens in any holder's account | | `non_transferable` | hard | The tokens can never be sent or sold | | `default_frozen` | hard | New holdings start frozen | | `transfer_fee` | hard | Transfers pay a fee, or someone can set one | | `pausable` | hard | Someone can pause every transfer, or already has | | `unknown_extension` | hard | A Token-2022 extension Fin has not reviewed | | `not_sellable` | hard | The data source's checks say it cannot be sold back | | `mint_authority`, `hook_authority` | soft | More can be created; the issuer can add a transfer rule later | | `low_liquidity`, `new_token`, `top_holders`, `unverified`, `low_organic`, `suspicious` | soft | Thin pools, mint or first trading pool under a day old, a few wallets hold most of it, not verified, mostly bot trading, flagged as suspicious | | `unpriced` | soft | No reliable price; a buy is refused because its loss cannot be bounded | The `new_token` warning covers limited history since mint creation or the first trading pool. `createdAt` and `firstPoolAt` stay distinct; neither date is inferred from the other. A hard flag refuses a buy; a sale is refused for all of them but a transfer fee and a pause authority that has not paused transfers. `blocked` means a hard flag, `unknown` means the mint could not be read (and a mint no one has read is never bought), `high` is two or more of the warnings that count (`low_liquidity`, `new_token`, `top_holders`, `unverified`, `low_organic`, `suspicious`) and `medium` one. `low` means none of Fin's checks raised a flag. It is not a statement that a token is safe, and nothing in your app should say so. `tradable` says whether Fin would buy the token now: its verdict is neither `blocked` nor `unknown`, it has a price, and it is not wrapped SOL, which a buy pays with. ## Discover memes and launches [List Solana tokens](/api-reference/solana/list-tokens) searches the sampled catalog and ranks matching candidates over a trailing window: ```http GET /v1/solana/tokens?lane=trending&interval=1h&limit=10 ``` The SDK equivalent is `user.solana.listTokens({ lane: "trending", interval: "1h", limit: 10 })`. Every query field is optional (`trending`, `1h` and 10 by default; at most 25). | `lane` | Ranks by | | --- | --- | | `trending` | Organic volume | | `traded` | Trading volume | | `organic` | The data source's organic score | | `new` | Most recent first-pool opening; category may remain unconfirmed | | `gainers` | Reported price change in the selected activity window | By default, membership is `meme`: positive classification evidence is required. The `new` lane defaults to `launches`, which can include unclassified launch candidates. Explicit `membership` selects `meme`, `launches` or `all`. Search and exact-token detail remain available for other Solana tokens. Wrapped SOL is never a discovery candidate. Young or thin memes are discoverable with their warnings. Supply `minLiquidityUsd`, `maxLiquidityUsd`, `minMarketCapUsd`, `maxMarketCapUsd`, `maxAgeHours`, `launchpad` or `tradableOnly` to narrow the result. USD filters are exact decimal strings. Missing figures do not satisfy numeric filters, and fully diluted valuation is never substituted for capitalization. The provider reader accepts USD figures with at most 15 whole digits; larger figures remain unavailable and fail numeric filters instead of being rounded into range. With `tradableOnly=true`, a failed RPC, price or Shield read returns retryable `503 provider_unavailable`; it does not count the unassessed candidates as non-matches or advance past them. A completed assessment that finds no reliable price, a blocked mint, or an absent or unreadable mint can legitimately return an empty `200` result. Without this filter, retained candidates remain inspectable with unknown assessments and buying disabled. `sort` selects `rank`, `liquidity`, `market_cap`, `age`, `change` or `move`, with optional `direction`. `change` orders by the signed price change in the selected window; `move` orders by its size whichever way it went, largest first, so `sort=move&limit=3` is the three tokens moving most. A token with no reported change sorts last under both. Token age and activity window are separate: selecting `5m` does not mean tokens launched in the last five minutes. Each row carries its `rank`, factual `reason`, membership, current risk and evidence. These activity rankings do not predict returns. A research recommendation grants no trading consent; an actual buy still requires the existing exact-token, amount and approval flow. `coverage.universe` is `sampled`. Coverage reports observed/eligible/returned counts, collection limits and each source's status. These are counts within the collected snapshot, not the total number of memecoins in existence. Inspect `status`, `asOf`, source timestamps and `dataGaps` before describing results as current. A failed source is not evidence that it found no tokens. A listing scans at most 32 source feeds and the newest 1,000 raw observations per feed before applying snapshot time bounds and selecting each mint's latest source facts. The combined catalog is capped at 10,000 source rows. `coverage.limitReached` reports when a bound narrowed coverage; seven-day retention does not mean every retained observation is scanned for a list. Exact-token search/detail use mint-targeted reads instead of scanning this discovery sample. ### Load another page Keep the same filters and pass `nextCursor` to continue the fixed snapshot. A null cursor means this snapshot has no more matching rows. Start a new query without the cursor to refresh it. Do not reuse a cursor after changing filters or interpret a snapshot identifier as authority. ```typescript const query = { lane: "trending" as const, membership: "meme" as const, minLiquidityUsd: "10000", limit: 25 }; const first = await user.solana.listTokens(query); const second = first.nextCursor ? await user.solana.listTokens({ ...query, cursor: first.nextCursor }) : undefined; ``` ## Ask Fin to research a candidate Discovery questions summarize the requested universe and activity. An explicit recommendation question compares a bounded shortlist and may conclude there is no convincing pick. A supported answer identifies the time horizon, observed basis, case against the choice, invalidation condition and missing evidence. New launches can be discussed with limited history; neither a model score nor a risk badge establishes future profitability. ## Draw a price chart [Get a token chart](/api-reference/solana/get-token-chart) answers a token's recent closing prices from its deepest pool, oldest first, at most 200 points: ```http GET /v1/solana/tokens/{mint}/chart?interval=1h ``` The SDK equivalent is `user.solana.getTokenChart(mint, { interval: "1h" })`; `interval` is `1m`, `5m`, `15m`, `1h`, `4h` or `1d`. Minute intervals support inspection of young launches. `coverage` states the actual sample span/count, latest completed period, gaps and freshness; a short or gapped history cannot support a longer trend claim. The model's read-only `solana_token_history` tool uses the same data. Each point keeps `closeUsd` and optionally includes `ohlcv` with exact `openUsd`, `highUsd`, `lowUsd` and `volumeUsd`. These are the selected pool’s candle values, not aggregate token volume or an executable quote. The API omits these optional dimensions when they are missing or inconsistent with the close. Exclude periods ending after `coverage.completedThrough` from completed-bar analysis. Empty intervals are not synthesized. Future-dated or malformed candle timestamps make the read unavailable with `invalid_response`; a fetch timestamp cannot make them current history. The provider’s [OHLCV contract](https://docs.coingecko.com/reference/pool-ohlcv-contract-address) defines the candle shape and USD denomination. A `status` of `unavailable` says why there is no chart: `no_pool` means no pool prices the token, and the other reasons mean the price source did not answer. It is never a price of zero. ## Draw a line for each row of a list [List token sparklines](/api-reference/solana/list-token-sparklines) answers a small price line for each token named, in one read for a page of a list: ```http GET /v1/solana/tokens/sparklines?interval=6h&mint={mint}&mint={mint} ``` The SDK equivalent is `user.solana.listTokenSparklines({ interval: "6h", mint: [first, second] })`. `interval` is `1h` (the default), `6h` or `24h`; repeat `mint` for up to 25 tokens, and each comes back once, in the order asked. An `observed` item has at most 32 `points`, oldest first, each a `time` and an exact `priceUsd`. They are the prices Fin itself sampled from the data source while the token was in the feeds it reads, so an answer costs no provider read, and it is kept for 30 seconds. Use [Get a token chart](#draw-a-price-chart) for one token's full chart. An `unavailable` item says why it has no line: `not_sampled` when Fin read no price for it in the window, and `too_sparse` when what it read would mislead, because there are fewer than 8 prices, the first comes later than 15% into the window, or any gap, up to now, is over 25% of it. Leave the line out then rather than draw what there is. It needs the `solana` feature; a window Fin draws no line for, a mint that is no address, more than 25 mints or none answers 400. ## Show where a token stands on its launchpad [List token launch status](/api-reference/solana/list-token-launch-status) says where each token named stands, in one read for a page of a list: ```http GET /v1/solana/tokens/launch-status?mint={mint}&mint={mint} ``` The SDK equivalent is `user.solana.listTokenLaunchStatus({ mint: [first, second] })`. Repeat `mint` for up to 25 tokens; each item has the token's `mint` and a `status`: | `status` | With | What it means | | --- | --- | --- | | `curve` | `launchpad`, `progressPct`, `observedAt` | It is on `pump.fun`'s bonding curve, read from the chain. `progressPct` is how much of what the curve sells has been bought, cut to two decimals: `5.50`. | | `graduated` | `launchpad`, `graduatedAt` | It left its launchpad's curve for an open pool, at the time the data source states. | | `unknown` | | Fin cannot say: no launchpad is named for it, its launchpad's curve is not one Fin reads, or the chain or the data source could not be read just now. | Only pump.fun's curve can be read, so a token on another launchpad's curve is `unknown`; the `launchpad` and `graduated` of a token read still say where it launched. A read of the chain is kept for 15 seconds, and nothing is stored. It needs the `solana` feature; a mint that is no address, more than 25 mints or none answers 400. For one token, [Get a Solana token](/api-reference/solana/get-token) states the same progress as `bondingProgressPct`, absent when it is on no curve Fin can read. ## Draw a token's icon A token's `iconUrl`, on a search candidate, a list row, a token read or a holding, is the path of [Get a token icon](/api-reference/solana/get-token-icon) for its mint: ```http GET /v1/solana/tokens/{mint}/icon ``` The SDK equivalent is `user.solana.getTokenIcon(mint)`, which answers `{ contentType, bytes }`. Fin fetches the icon the data source lists itself, so the person's browser never asks the token creator's server for it, and answers it only as a PNG, JPEG, WebP or GIF, with `Content-Type` read from the image's own bytes, `X-Content-Type-Options: nosniff` and `Cache-Control: private, max-age=86400`: a day in the caller's own cache, never a shared one. Like every route it needs the user's session and your partner key, so an image tag reaches it through your own server. It answers 404 when there is no icon Fin will serve: none listed, or one that is unreachable, larger than 2 MiB (2,097,152 bytes), not one of those four types, or on an address that is not public. Draw a placeholder then. If a public IPFS gateway listed for an icon answers 429, Fin can read that same content identifier and file path through its existing artwork gateway. Both attempts share the same three-second deadline, one-redirect limit and image checks; the browser still reads only Fin's icon route. ## Trade a token from your own screen A user can buy or sell a token from its page with one signature and no agent run. The trade runs through the same checks, policy worker and Solana sequence as a buy or sale the agent proposes and the user approves in chat; only who asked differs. It takes two calls and a read. 1. [Prepare a Solana trade](/api-reference/solana/prepare-trade) with the buy or sale, in the shape the agent's `solana_buy` and `solana_sell` take: the token's `mint`, `decimals` and `tokenProgram` exactly as [Get a Solana token](/api-reference/solana/get-token) read them, what it pays or sells, and an explicit `maxValueLossBps` from 1 to 1,500. Fin checks it as it checks the agent's own and answers the exact `trade` to show, `authorization.message` for the user to sign and the `requestKey`. Nothing is reserved, opened or moved. ```http POST /v1/users/{userId}/solana/trades/prepare ``` 2. Show the trade, have the user sign `authorization.message` with the wallet or passkey they signed in with, and [place the trade](/api-reference/solana/place-trade) before `authorization.expiresAt`, with the prepared `requestKey` as the `Idempotency-Key`: ```http POST /v1/users/{userId}/solana/trades Idempotency-Key: {requestKey} { "trade": { ...the prepared trade, unchanged }, "authorization": { ...the signed authorization } } ``` It answers `201` with the `SolanaTrade`, its `status` `processing`, and a `Location` header naming it. If the call times out, send it again unchanged: you get the same trade, never a second one. A different body under the same key is `409 request_key_conflict`. 3. [Get the trade](/api-reference/solana/get-trade) until its `status` is no longer `processing`. `stage` names the step it is on (`funding`, `swap` or `sweep`) once one began. Its status reads as a Solana activity item's does, `paid`, `received` and `transactions` included, and it is final by `completeBy`. The SDK equivalents are `user.solana.prepareTrade(body)`, `user.solana.placeTrade(body, { idempotencyKey: prepared.requestKey })` and `user.solana.getTrade(tradeId)`. The signed message names `completeBy`: a trade that starts while the signature lasts may finish up to nine minutes after it, because a USDC buy first moves USDC to the agent's Solana account as SOL through 1Click and only then swaps on Jupiter, and a sale for USDC swaps, then sends its proceeds back. Nothing starts after the signature lapsed, and nothing runs past `completeBy`. A buy needs the `solana` feature (`403 solana_disabled`) and opens the agent's Solana account itself the first time; it moves nothing to do so. A sale needs no feature, so a user can always sell what they hold, but it needs the opened account (`404 no_account`). A token Fin does not trade is `403 solana_token_not_tradable`, read [Fin's risk verdict](#fins-risk-verdict) before offering a buy. One trade runs at a time per user: placing a second while one runs is `409 solana_trade_changed`, as is a token whose decimals or program changed under the signed trade; prepare it again. While an operator pauses trading, placing answers `503 unavailable`, retryable, and a trade already running stops with nothing more moved. Trades placed this way are in [List activity](/api-reference/activity/list) as `solana_trade` items, each carrying the trade Get a Solana trade returns, apart from the agent's own `solana` items (and its `solana_sell_many` items, a sale of several coins under one approval) and left out under `origin`. When one ends, Fin notifies the user with a `trade` notification whose subject is `{ "type": "solana_trade", "tradeId": "…" }`, so a user who left the page hears how it ended (see [notifications](/notifications)). The agent's Solana balances change with them, so read [Get the Solana account](/api-reference/solana/get-account) again once one ends. ## Show where the data comes from Answers carry their source and when it was read (`source.name`, `source.observedAt`; a chart's source is its price provider's). Show it beside the figures, such as "Data: Jupiter". Prices, liquidity and activity are the data source's own figures, converted without rounding, and not a quote: the price a trade gets is what its approval card and receipt state. Token and list answers are cached for up to thirty seconds, and charts for a minute, so a read repeated at once returns the same figures and the original observation time. Catalog discovery refreshes independently of a user's page. Provider update time, collection time and the user's most recent request are different facts; do not reset the market's apparent age when displaying cached data. ## Financial endings and late confirmation Solana approvals preserve exact price thresholds and the complete signed standing definition, even in a compact card. A standing firing renders the financial result without requiring a second approval for that call. `pending`, `partial`, `not_executed` and refused outcomes must not be displayed as successful settlement. A recorded refusal is a failed tool result with a denial code and repair advice; a later user request needs fresh approval. A multi-coin sale (`solana_sell_many`, two to six coins under one approval, each sold on its own and then one transfer back) reports every coin in its outcome's `solana.sales` (`sold` with what it paid and the SOL its swap added, `not_sold`, or `uncertain` while a swap of it may still land, each with its own swap `transactions`) beside `received`, the whole sale's total; its `solana.transactions` lists only the transfer back, and it names no one `token` or `paid`. It is `not_executed` when no coin sold, `partial` when a coin sold but the transfer back did not finish (or the user kept SOL, `solLeftLamports` the summed gain), and `settled` once the one transfer settled. Its progress names the coin each swap sells (`sale`) and no `transactionIndex`. `solana.reconciled` can correct a completed tool's still-pending financial result. Refresh the Solana account and balances when its financial status or reconciliation payload changes, even when the outer tool status remains `completed`. A missing transaction status alone never proves non-execution: retained history must cover the immutable pre-sign slot, otherwise Fin keeps the operation uncertain. USDC withdrawals recheck the approved loss floor against fresh SOL prices at signing, preserving the stricter of the original and fresh floors. --- # Automations An automation is a task the agent runs on its own: on a schedule, when a condition becomes true (for example a price crossing a level), or when your system sends it an event. Users create and edit automations by asking the agent in a conversation; the API lets you list them, show them, pause, resume and delete them, and send them events. There is no direct route to create or edit one, and none to run one on demand: an automation runs only on its own schedule, condition or events. An automation never gets permission to move money just by running. A trade it proposes needs the user's approval, unless the user approved limits for it when it was created: then its scheduled runs can trade within those limits. Those limits can include paying out to destinations the user approved; a run can never pay any other. For new automations with approved NEAR Intents trading limits, entries can run only at a set time, on an interval or calendar schedule, or when a 1Click token-price reading updates (`at`, `interval`, `calendar`, `reader_update`). Entry conditions and price-update wakes must use `oneclick.token_price` for the first entry swap's pinned input/output pair; tokens used only by a later action cannot trigger an entry. Unused readers may name other tokens pinned by approved actions. The only non-1Click exception is the reviewed push-only exit pair below. Events, other readers and unpinned tokens are refused before approval. A schedule with no readers and an always-true condition is allowed. Automations without a contract keep their existing source and event support, but gain no permission to spend. The agent's creation tool reports an unsupported contract trigger with `status: "failed"` and `error.code: "invalid_input"`. Its diagnostic names the refused field and includes a message beginning `contract_trigger_unverifiable`. The consent check independently refuses it as `invalid_input` with the same message prefix; no approval is opened. There is no separate automation creation endpoint. For an automation with trading limits, Fin checks each firing against a **1Click signed dry quote**, not just a saved price reading. Price-based entries use the quote's exact USD-per-token ratios for the first selected swap's pinned input and output tokens; a condition requiring another token cannot authorize a trade. The quote uses the approved exact-input quantity, or one whole input token for other quantity rules. Fin independently checks the signature, pair, amount and condition before allowing that firing to trade. Both checks use the same signed numbers, with **no tolerance band**. Clock-only entries that read no price and have no reader-update wake use only 1Click's signed timestamp. A payout-only automation obtains a dry reference quote for one canonical USDC → wNEAR; this moves no funds, adds no action and does not price the approved payout. Its approved payout amount and recipient remain unchanged. Price-based entries and exits still require their exact quoted pair and amount. Fin's trusted clock decides freshness: the signed quote must be no more than 30 seconds old or 5 seconds ahead. Scheduled checks must name a real slot of the saved schedule and be within 60 seconds of both that clock and the signed quote timestamp. Periodic exits likewise require a real slot of their saved interval. A 1Click quote outage, stale quote or temporary sealing conflict leaves the check unconsumed for a later retry; none can authorize a trade. Invalid or nonmatching quotes may leave a refused proposal, but no permission to trade. These checks also apply to already saved contract-backed automations, without changing automations that have no trading contract. For a “becomes true” trigger, Fin independently verifies that the condition holds now, not the entire history of its transition. The scheduler still tracks that history; Fin separately enforces the approved once-only/run-count/cooldown bounds and financial limits. Entry limits do not disarm position exits. A schedule like "every day at 9am" is read in the time zone you send with that message in `context.timeZone` (see [Start a run](/api-reference/runs/start)); without one, the agent asks the user. The automation keeps that zone, through daylight saving too, even after the user travels. A user who moves can ask the agent to edit the saved automation's zone in chat; the change takes effect only after approval of the exact resulting definition. Send `context.country` from your server's edge geolocation with every message too, including requests to create a tokenized-stock automation. Purchases require an allowed country and an operator-enabled `tokenized_stocks` flag; these assets can only be sold, never withdrawn or sent. See [Tokenized stocks](/concepts#tokenized-stocks). Examples use the variables from the [quickstart](/quickstart). ## Deadlines and missed runs Every automation has a deadline, `rule.maxDeliveryLatenessSeconds`, from 1 to 86,400 seconds: how late after it fires a run may start and sign. A schedule's deadline can't be longer than the shortest gap between its runs; the agent chooses it from how time-sensitive the request is. A contract's signed windows follow from the deadline, so the approval shows one set of terms and nothing is chosen twice. `missedRun` on an automation, `skip` or `ask`, is what happens to a run that can't go through before its deadline. `skip` counts the run, keeps the schedule and tells the owner once per streak of failures. `ask` pauses the automation and asks the owner, with `waitingForOwner` set. A fault on Fin's side keeps the schedule whichever is chosen, unless it took a rule's last run. The agent chooses it, and an owner can change it by asking in chat. It reads `ask` when none was chosen. A failure only the owner can fix, like an empty wallet, pauses whichever is chosen. ## Perps automations An automation can also act on the agent's own Hyperliquid account (see [Open a perps account](/wallet-transfers#open-a-perps-account)): reduce or close a position, or add margin to the account, when a condition Hyperliquid's own orders cannot express holds. A fixed take-profit, stop-loss or trailing stop stays a native order on the position (`perps_order_place`, see [Approve perps orders](/wallet-transfers#approve-perps-orders)); an automation is for conditions such as the funding rate, open interest, the margin ratio, distance to liquidation, unrealized PnL or a time. Choose the two reviewed recipes for the contract coin's dex. Main-dex coins use `hyperliquid.market` / `hyperliquid.position` with `{ "coin": "BTC" }` (or its listed main-dex name). trade.xyz coins use `trade_xyz.market` / `trade_xyz.position` with `{ "coin": "xyz:TSLA" }` (or its full listed `xyz:` name). Never mix source families. Take both the full coin and global asset id exactly from `perps_markets`. - `hyperliquid.market` or `trade_xyz.market` (public): `markPriceUsd`, `oraclePriceUsd`, `midPriceUsd` (optional), `fundingRatePerHour` (signed), `openInterestAsset`, `openInterestUsd`, `dayVolumeUsd` and `dayChangePercent` (signed). - `hyperliquid.position` or `trade_xyz.position` (the agent's own account): `positionSizeAsset` (signed; `0` when flat), `side` (`long`, `short` or `flat`), `entryPriceUsd`, `markPriceUsd`, `liquidationPriceUsd` and `liquidationDistancePercent` (optional), `unrealizedPnlUsd`, `returnOnEquityPercent`, `marginUsedUsd`, `leverage`, `accountValueUsd`, `maintenanceMarginUsd`, `marginRatioPercent` and `spotUsdcAvailable`. Values are exact decimal strings with the units the source catalog lists. All are polled snapshots; Hyperliquid gives no observation time, so each reading is stamped when fetched. Account value, maintenance margin and margin ratio belong to the selected dex; `spotUsdcAvailable` is shared account-wide collateral, not additive across dexes. Existing main-dex source bindings keep their identities and require no migration. The money it may move is a `perps_automation` contract the user approves (and signs, as for any automation with trading limits) when the automation is created: ```json { "type": "perps_automation", "coin": "BTC", "asset": 0, "position": "long", "action": { "kind": "reduce", "fractionBps": 5000, "maxSlippageBps": 100 }, "maxExecutions": 3, "validUntil": "2026-11-16T00:00:00.000Z" } ``` - `open` (`{ "kind": "open", "notionalUsd": "200", "leverage": 3, "marginMode": "cross", "maxSlippageBps": 100, "takeProfitPercent": "10", "stopLossPercent": "5" }`) opens the named position with a market order of `notionalUsd` at the mark when it fires (at most two decimal places), sized in the coin by rounding down to the market's size step, at exactly that leverage and margin mode, no worse than `maxSlippageBps` (at most 500) from the mark. It acts only while the agent holds nothing on the coin: it never adds to or flips a position, so a repeating open enters again only after the position is closed. `takeProfitPercent` and `stopLossPercent` (above 0 and below 100, or `null`) become native Hyperliquid exits that far from the mark it opened at, each filling within `maxSlippageBps` of its trigger. Fin checks the position again before signing and before sending either the leverage setting or entry; an unanswered opening on that market blocks another automated open. These venue reads are not an atomic flat-only condition at Hyperliquid, so avoid overlapping resting entries on the same coin. - `reduce` closes `fractionBps` of the named position (`10000` closes it all) with a reduce-only market order no worse than `maxSlippageBps` (at most 500) from the mark. Nothing happens while the agent is flat or holds the other side. - `add_margin` (`{ "kind": "add_margin", "amountRaw": "25000000", "maxValueLossBps": 100 }`) moves exactly that USDC (six decimals) from the agent wallet into the perps account, losing at most `maxValueLossBps` (at most 300) to fees. It too acts only while the agent holds the named position: nothing happens while the agent is flat or holds the other side. Each firing that acts uses one of `maxExecutions`; the automation ends when they are used or `validUntil` passes, and deleting it revokes the contract. Its rule may read only those two recipes for the contract's own coin, with `at`, `interval`, `calendar` or `reader_update` wakes; anything else is refused with `contract_trigger_unverifiable` before approval. An entry at a fixed price is a resting limit order, not an automation. A saved observation never moves money by itself. When the rule fires, Fin's policy worker reads Hyperliquid itself, checks the rule again on what it read, and computes the exact order or funding from the contract and that state; the run submits exactly that call and nothing else, and no other perps write is available to it. A reduce is an exit and is never gated. Opening a position or adding margin needs the user's `perps` feature and an allowed region: the latest `context.perpsAllowed` your server reported on one of the user's runs must be `true` and at most 7 days old, because no one is present when it fires. Otherwise the firing is refused with `not_available_in_region` and nothing moves; report `context.perpsAllowed` on every run so it stays current. `Automation.contract.terms` returns the approved contract; narrow on `terms.type`. `spendUsed` is what counts against the cap, in-flight amounts included; show `settledSpend` for what the automation actually spent. For a perps or Polymarket automation both are empty and `executionsUsed` counts the firings that acted. Each run's `perps` field is what that firing did on Hyperliquid: `{ kind: "order" }` with the exact `order` it placed (reduce-only for a `reduce`, opening for an `open`) and Hyperliquid's `outcome` (each placement's fill), or `{ kind: "margin" }` with the `transfer` it moved and how it ended. `outcome` is `null` while the order or transfer is still under way; the run never sends it twice. ## Polymarket automations An automation can trade one Polymarket outcome on its own odds: "buy $50 of Yes when its chance drops below 30%", "sell half my Yes once it is above 70%". The user approves a `prediction_automation` contract when the automation is created; it is never edited (archive it and create another): ```json { "type": "prediction_automation", "market": { "marketId": "12345", "conditionId": "0x…", "assetId": "123456789…", "marketQuestion": "Will the Fed cut rates in December?", "outcome": "Yes" }, "action": { "kind": "buy", "amountUsdDecimal": "50", "maxPriceUsdDecimal": "0.32", "maxFeeUsdDecimal": "1" }, "maxExecutions": 3, "validUntil": "2026-12-31T00:00:00.000Z" } ``` - `buy` places an immediate order of `amountUsdDecimal` pUSD (to the cent) paying no more than `maxPriceUsdDecimal` a share; what the book does not fill at once is cancelled. Every firing places the same order, so it spends at most `maxExecutions` × `amountUsdDecimal` before fees. - `sell` (`{ "kind": "sell", "fractionBps": 5000, "minPriceUsdDecimal": "0.7", "maxFeeUsdDecimal": "1" }`) sells that share of the agent's holding of the outcome at no less than `minPriceUsdDecimal`; nothing happens while it holds none. `market` is copied exactly from the agent's market lookup; a market's Yes and No are different `assetId`s. The rule may read only polled `polymarket.outcome` readers of that same outcome and compare only `bestBidUsdDecimal`, `bestAskUsdDecimal` or `midpointUsdDecimal`, with `at`, `interval`, `calendar` or `reader_update` wakes; anything else is refused with `contract_trigger_unverifiable` before approval. When it fires, Fin's policy worker reads the order book itself, checks the rule again on what it read and places exactly the order the contract implies; a closed or resolved market has no book, so nothing trades. It needs the user's `prediction` feature and a ready Polymarket account. Each run's order appears among the user's Polymarket orders, and `executionsUsed` counts the firings whose order was signed. ## Cross-venue triggers An automation that trades on one venue can be timed by what happens on another: "buy 200 USDC of BTC once Fed-cut odds pass 70%", "sell my Yes if BTC's Hyperliquid mark falls below 90,000", "close half my BTC long when Fed-cut odds pass 70%". Any trading contract's rule may add a polled reader of another venue and compare it in the entry condition only: | Reader | Compared by | |---|---| | `polymarket.outcome` | `bestBidUsdDecimal`, `bestAskUsdDecimal`, `midpointUsdDecimal` | | `hyperliquid.market`, `trade_xyz.market` (any coin) | the market fields, such as `markPriceUsd` | | `oneclick.token_price` (any token; not for a NEAR Intents contract, whose 1Click readers are its own) | `priceUsdDecimal` | | `jupiter.token_price` (any mint) | `priceUsdDecimal` | Such a reader is woken by nothing: the rule uses an `at`, `interval` or `calendar` wake. A `reader_update` wake on it, a `rule.exit` that reads it, another field, a push feed or a webhook is refused with `contract_trigger_unverifiable` before approval. The contract still says exactly what is traded, with what bounds and how many times; before it signs, Fin's policy worker reads the other venue itself and checks the condition again, and a NEAR Intents buy is still priced by 1Click's signed quote. ## Edit through chat Send the correction as an ordinary message, such as “move my daily report to 10 AM in America/New_York.” The agent searches the owner's automations and asks when the target is ambiguous, reads the complete editable definition and snapshot, then proposes `automations_edit`. The approval shows the exact target snapshot, current definition, requested differences and complete resulting definition. No definition is reconstructed from a readable summary. Every edit needs exact approval; if either definition permits financial actions, even a rename or removing those permissions needs a new owner signature through the existing wallet authorization flow. Unchanged caps/expiry retain prior spent, used and reserved allowance; the approval shows resulting remaining allowance, not a renewed budget. Open positions needing their approved exits and unresolved financial operations block editing. A stale proposal needs a fresh read and approval. Editing keeps the automation ID/history and paused state, does not clear an operator hold and cannot restore an archived automation. A completed tool receipt names the committed `definitionVersion` and `activationEpoch`. Render it from durable journal replay and refresh the same owner-scoped automation read used by your detail page; never let a cached older version replace the receipt. Old admitted runs retain their original version/evidence and signed effects still reconcile. When `webhookSetupRequired` is true, obtain a new webhook key on Manage and update the sender; no secret is returned to the agent. Commit is not proof of source health, a next firing, policy acknowledgement or settled money movement. ## List and read automations ```bash curl --fail-with-body -sS "${FIN_AUTH[@]}" \ "$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations?filter=current&limit=20" ``` `filter=current` shows running and paused automations and hides deleted ones; `enabled`, `paused` and `deleted` narrow further, and `all` (the default) includes everything. `query` searches names and instructions. [Get an automation](/api-reference/automations/get) returns everything about one: - `name`, `prompt` (the instructions the agent follows) and `summary`, a sentence describing when it runs, ready to show; - `definitionVersion`, the committed saved-definition revision. This server always returns it; the SDK keeps it optional for earlier servers. Until a read proves a version at least as new as an edit receipt, keep that receipt visible rather than replacing it with stale state; - `enabled`, `nextFireAt` and `monitoring`, which reports whether its data sources are healthy and what the condition last evaluated to. A news exit (`rule.news`) has no sources or webhook of its own: its `monitoring.webhook` is always `null`, and its `monitoring.status` is `healthy` while Fin's news judge checks the news for it, or `unavailable` (with a `reason` saying news checks are paused) while news exits are off for the user. Never ask for a webhook key for one; - `activeRun` and `latestRun`; - `contract`, when the user approved trading limits for it: the limits, and how much of them has been used. `rule.exit` describes the position exits a contract may carry: how often the agent re-checks them and the pinned pair used for their signed quote. For a contract automation, the asset reader names the exit action's pinned input token and the quote reader its pinned output token, both through `oneclick.token_price`. New latency-sensitive position exits may also use fast price updates when enabled for the user. `rule.exit.push.readers` names the supplementary asset and quote readers: only `kraken.asset_price` or `consensus.asset_price`, with `delivery: "push"`. They must price each exit action's exact pinned input and output tokens respectively, not just other tokens in the approved actions. They may be referenced only by `rule.exit.push.readers`, never in the entry condition at any depth or in either operand, or by a `reader_update` wake. `rule.exit.intervalSeconds` remains the periodic 1Click check interval. Existing automations keep their approved monitoring plan. Users do not need to choose a transport or configure a price-feed connection. Show both the saved plan and `monitoring.sources`. Saving alone does not mean updates are arriving. The agent saves an automation only on data sources this deployment serves: a shared source it does not offer is listed with `availability.status: "unavailable"` in [List automation data sources](/api-reference/automations/list-sources), and the agent picks another that reads the same fact or tells the user why it can't. A plan blocked on the user's own step, such as creating their agent wallet, is saved with `status: "needs_connection"` and starts monitoring once they finish it and resume the automation. An unavailable or stale supplementary feed reports `monitoring.status: "stale"` with a reason explaining the periodic fallback; an unavailable required source reports `"unavailable"`. A fallback check needs a fresh signed 1Click quote. Fast sources are public venue prices — preferably the median of Kraken and Coinbase, which publishes nothing while the venues disagree by more than 1% — and can differ from 1Click. Coinbase participates in consensus; it is not a separate reader operation. These feeds are **wake hints only** for contract-backed exits: they decide when an exit gets checked. The guard uses the signed input USD-per-token price divided by the signed output USD-per-token price: a **fee-neutral** output-token-per-input-token rate, not the net executable amounts or catalog prices. Fees and spread must not produce a false stop-loss at an unchanged market price. Fin independently recomputes this automation's own position and approved fraction before authorizing the firing, and checks its plan against that same verified rate. The trigger quote's amount is not capped by wallet balance; the actual sale still is. Fresh execution quotes and ordinary balance and loss limits remain required. A brief move, reconnect gap or particular execution delay is not guaranteed to be covered. ## Solana tokens An automation can watch a Solana token's price with the `jupiter.token_price` reader, which names the token by its mint and reads Jupiter's Price v3 at most every 30 seconds. Without trading limits, such an automation is an **alert, not an automatic exit**: when it fires, the agent tells the user and proposes the sale as a `solana_sell` approval that waits for them. The run never buys and never sells on its own. The user can also approve standing limits for a Solana trade when the automation is created: its `contract.terms.type` is then `solana_buy` or `solana_sell`. Each firing makes exactly the approved trade, never another token, amount or loss bound: - `solana_buy` buys the token named by its mint with the approved amount, at least 5 USDC when paid in USDC. Creating one needs the user's `solana` flag, as any Solana buy does. - `solana_sell` sells a share (`amount.kind: "fraction"`) of what the agent's Solana account holds of the token when the firing runs, for USDC on NEAR (`receive: "usdc"`). It never sells an exact amount the account may no longer hold. Selling is never gated by the flag. - `maxExecutions` and `validUntil` bound how many firings may trade and until when. `contract.executionsUsed` counts the firings that started trading, settled or not. Such an automation can fire only on a schedule (`at`, `interval`, `calendar`) or when its own `jupiter.token_price` reading of the traded mint updates (`reader_update`); its condition may compare only that reader's `priceUsdDecimal`. A take-profit or a stop-loss is a `solana_sell` whose condition reads the price, so `rule.exit` is refused, as are event wakes, other readers and another token's price, before any approval opens, with a message beginning `contract_trigger_unverifiable`. So is a `solana_buy` that wakes on `reader_update` and compares no price: it would buy at every reading and use up its executions within minutes. Give it a price condition, or wake it on a schedule. Before a firing may trade, Fin's policy service checks it itself. A scheduled firing must name a real slot of the saved schedule, within 60 seconds of Fin's own clock. A price condition is re-evaluated on Fin's own read of Jupiter's Price v3 for the traded mint, with no tolerance: the price must have last changed within about ten minutes of Fin's own Solana network reading. The scheduler's reading only proposes the firing. If Fin's read disagrees, is stale, or Jupiter or the Solana network does not answer at that moment, that firing's run cannot trade, and it still counts as the rule's firing: a once-only rule does not fire again, while a repeating rule's next firing is checked afresh. Read a standing trade's financial result on the automation run's `solana` field. It names the activity item's `id`, `kind` (`buy` or `sell`), exact admitted `request`, and observed `outcome`. It is null or absent before the run acts and for other automations; `outcome` is null while no result is recorded. A `pending` result still needs observation even when `runStatus` says `completed`. A `partial` result can leave SOL in the Solana account; show only the amounts the outcome records. A provider refund status alone does not prove the refunded amount. This also appears on `activeRun` and `latestRun`, so the list and run detail can show the same financial state. Solana trades are not returned by the Intents wallet-trades listing. A standing Solana automation cannot be edited: delete it and ask the agent for a new one with the terms the user wants. ## Pause, resume and delete ```bash FIN_AUTOMATION_URL="$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations/$FIN_AUTOMATION_ID" curl --fail-with-body -sS "${FIN_AUTH[@]}" -X POST "$FIN_AUTOMATION_URL/pause" curl --fail-with-body -sS "${FIN_AUTH[@]}" -X POST "$FIN_AUTOMATION_URL/resume" curl --fail-with-body -sS "${FIN_AUTH[@]}" -X DELETE "$FIN_AUTOMATION_URL" ``` Pausing stops the automation and cancels runs that were waiting to start; runs already going finish, but a run that started before the pause can't trade. Deleting stops it for good, and its history stays readable. If the automation has trading limits, pausing keeps them: resuming carries on under the limits the user already approved, with no new signature. Resume is refused (`409 automation_invalid`) once those limits have been revoked, or when a data source it reads is no longer offered; the user then sets the automation up again by asking the agent. Resuming an automation whose source was waiting on the user's own step is how it starts monitoring. Fin pauses an automation itself when a run can't go on and only its owner can decide: its wallet can't pay, it can't run as written, or a run missed its deadline with `missedRun: "ask"`. Under `ask`, a failure that took a rule's last run pauses too, for every kind of automation. Fin also pauses an automation whose data source can no longer be read until its owner resumes it, such as one whose source a release changed, once it has gone fifteen minutes without a reading. `enabled` reads `false` and `waitingForOwner` names what the automation needs (`action`: `add_funds`, `edit_automation`, `decide` or `resume`), why it stopped (`reason`), the run it stopped at (`runId`) and when (`since`). No run stops a `resume` pause, so its `runId` is `null` and its `reason` reads `unavailable`. The owner gets one `waiting` notification; nothing retries or fires until they answer, and fin never moves money over a pause. Only the owner ends one: - **Resume** starts it again from its next slot and runs nothing it missed. For `resume`, it reads the data source again as it is now. The run it paused over goes back to the run limit. Pass `countMissedRun=true` when the owner lets that run go, so it counts; a rule that runs once then ends. A value that isn't a yes or a no (`true`, `false`, `1`, `0` and the like), or any parameter it doesn't know, answers `400`. Without a pause the parameter changes nothing. - **An edit through the agent** answers it: the run goes back, `waitingForOwner` clears and the automation stays paused until it is resumed. - **Delete** stops it, and the run counts. `runCount` leaves out the run it waits over until the owner chooses. `skippedRunCount` says how many runs were skipped: they failed, counted and left the schedule as it was. The `waiting` notification reads `status: "done"` once the pause is over. An operator can also hold an automation. A held automation answers `409 automation_held` until the operator releases it; the user can't lift a hold. Every creation, pause, resume and deletion also appears in [List activity](/api-reference/activity/list) as an item of `kind: "automation"`. An automation an operator retires, or one that finishes on its own, shows there as `deleted`, the way Get an automation reports it. Edits are retained privately and shown in their chat receipt and automation detail, not in this unchanged `/v1` activity contract. The server excludes `edited` rows before limits and cursor pagination, so they do not consume visible pages or affect their item counts. ## See what it did ```bash curl --fail-with-body -sS "${FIN_AUTH[@]}" \ "$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations/$FIN_AUTOMATION_ID/runs?limit=20" ``` Each automation run records when and why it happened, whether the agent ran or it was skipped (for example because the previous run hadn't finished), the agent run it started and any approvals waiting. Its `selection` says what the firing ran: an entry firing runs the automation's buys in order, while an exit firing runs one take-profit or stop-loss sale of what the automation itself bought. Each one runs in a fresh conversation. A finished run doesn't prove a trade settled: read the trade under [Deposits, withdrawals and trades](/wallet-transfers#trades). `runNumber` says which of the automation's own runs this is, counting from 1, the number its run limit counts. It is `null` for a run that isn't a firing of its own, such as an exit selling a position. `deliverySequence` runs across every automation, so use it only to page, never to show. On the automation, `runCount` is how many numbered runs it has had (leaving out one it waits on its owner over) and `harvestCount` how many times it has harvested a gain, so you never need to infer either from `latestRun`. Treat `state` as a closed list that will grow. A started run reads `accepted` while it works and `retrying` while it waits to try again before `deadlineAt`, the latest it may still try: a trade a temporary outage refused before anything of it was planned or signed repeats until then and tells nobody until it ends. It then reads how it ended: `succeeded`, `partial`, `failed`, or `uncertain` when money may have moved and how it ended isn't known yet. A run that went through after trying again reads `succeeded` with `attempts` above 1. A `failed` or `partial` run's `reason` is one of `unavailable`, `insufficient_funds`, `empty_input` (there was nothing of it to sell), `quote_rejected`, `not_authorized`, `not_executed` or `condition_passed`, the last when the rule's condition stopped holding while it waited. To draw what an automation watches, read its sources over time: ```bash curl --fail-with-body -sS "${FIN_AUTH[@]}" \ "$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations/$FIN_AUTOMATION_ID/readings" ``` [List automation readings](/api-reference/automations/list-readings) answers one entry per reader in the rule: its `latest` good reading (the whole snapshot, for example a perps position's size, mark and liquidation price) and, for each field the rule's condition compares, the values over the window as exact decimal strings, at most 240 points, oldest first. The window is the last 30 days unless you pass `since` and `until`, at most 90 days apart; plot the rule's thresholds over it and each run's `evidence.evaluatedAt` on it. ## Send it events An automation without a contract can run on incoming events and has its own webhook. New contract automations cannot use event wakes. Create the event automation's secret: ```bash curl --fail-with-body -sS "${FIN_AUTH[@]}" \ -X POST "$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations/$FIN_AUTOMATION_ID/rotate-webhook-secret" \ > webhook.json FIN_WEBHOOK_PATH=$(jq -er '.path' webhook.json) FIN_WEBHOOK_SECRET=$(jq -er '.secret' webhook.json) ``` The secret is shown once. Give it only to the system that sends the events. Rotating again replaces it at once, and pausing, resuming or deleting the automation also retires it. An automation that doesn't run on events answers `409 automation_has_no_webhook`, and so does a news exit: only Fin's news judge delivers its `news.judged` event. Your system then posts each event to the returned path with the secret in `X-Automation-Key` (not your API key or a session token): ```bash curl --fail-with-body -sS -X POST "$FIN_BASE_URL$FIN_WEBHOOK_PATH" \ -H "X-Automation-Key: $FIN_WEBHOOK_SECRET" -H 'Content-Type: application/json' \ -d "$(jq -n --arg at "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ '{id:"invoice-123",type:"invoice.paid",occurredAt:$at,data:{paid:true}}')" ``` | Answer | Meaning | | --- | --- | | `202` | Recorded. Whether the automation runs depends on its condition. | | `200` | You already sent this event `id`; nothing new happened. Resending is safe. | | `400` | The event is malformed, too old (over 5 minutes) or too far in the future (over 5 seconds). | | `401` | Wrong or retired secret. | | `409` | This event `id` was already sent with different content. | | `410` | The automation has finished for good. | | `429` | More than 60 events a minute; wait for `Retry-After`. | Events are at most 16 KiB. A recorded event doesn't mean the condition matched or that the agent ran; see the automation's runs for that. ## Preview historical behavior Call `fin.user({ userId, token }).automations.backtest(input)` to replay a draft definition or one saved automation over a past window. Select the hypothetical funding assumption: - Set `contributeInputs: true` and `initialHoldings: []` for independent, fixed-size entry swaps. Each successful modeled entry receives its full input token debit as an external contribution at fill time. The account starts empty; skipped, refused and unfilled entries add no funds. Later entries receive new contributions even if earlier exit proceeds remain. Exits only spend positions accumulated by the replay. Percentage/all-balance entries, portfolio-value conditions and recycling entry templates require a starting portfolio instead. - Omit `funding` and `contributeInputs` and supply exact `initialHoldings` (token identity, decimals and raw quantity) for a finite portfolio, percentage sizing or reinvestment. Starting assets are explicit assumptions, including an intentionally empty portfolio; live balances are never imported. - Set `funding: "strategy_budget"` with `initialHoldings: []` to retain finite upfront funding. It sets aside entry sizes times maximum runs at opening historical prices, or explicit total-input token caps. Uncapped balance-relative entries receive a disclosed $1,000 per input token. Read the resolved `scenario.initialHoldings` and limitations. Later price changes can exhaust that finite budget. This is not a contribution-funded replay. For contribution-funded reports, retain `contributions` beside `trades`: each row identifies the input token, raw quantity, action index, fill time and its USD value at that time. Profit excludes those funds: `endingValueUsdDecimal - startingValueUsdDecimal - contributedValueUsdDecimal`. Each equity point includes cumulative contributed value so the chart can make the same subtraction. The percentage is profit divided by total starting and contributed capital, not an annualized or time-weighted return. The no-trade comparison keeps the same contributed input tokens instead of swapping them; drawdown is adjusted for incoming capital using a reporting index rounded down at each mark to 36 decimal places, with exact money and trade arithmetic. If that index cannot represent a positive value, the report is incomplete with `performance_precision_limit`, without final metrics. Starting-portfolio and finite-budget reports retain their existing response shape. `report_value_limit` means modeled values exceeded the report's supported bounds; the response retains its scenario identity without financial metrics or unrepresentable detailed values. `starting_portfolio_required` means the selected contribution policy cannot size or finance that strategy; retry with explicit holdings and neither automatic funding option. Never replace that outcome with a zero-profit claim. Only `estimated` reports with metrics support financial performance. All scenarios retain their run/spend limits regardless of the historical window. Trade amounts are frozen at admission and filled at a later observation; input prices can change before fill, so a fixed-dollar instruction's contributed USD value can differ from its admission value. These holdings and contributions never reconstruct the user's historical wallet. Choose `preserved` timing to require compatible observations or `sampled` to accept explicitly listed timing changes, plus hourly/daily resolution and modeled cost basis points. The report identifies the scenario, data hash, observation assumptions and limits. Show performance only for `status: "estimated"` with non-null metrics; incomplete, unavailable and trigger-only results must retain their reason and limitations. A replay grants no approval or standing consent, and changes no automation. Two definitions answer `status: "unavailable"` before any history is read. A contract other than a NEAR Intents transfer, such as a perps automation or a standing Solana buy or sell, gives `reason: "unsupported_contract"`. A rule that watches a Solana token's price (`jupiter.token_price`) gives `reason: "unsupported_source"`, because no historical source covers that price. Historical collection can take up to five minutes. For SDK calls, configure a dedicated client with `timeoutMs: 310_000` and pass an `AbortSignal` so leaving the preview cancels collection. Keep starting balances and the date window fixed while presenting a result; request a new replay when any assumption changes. Retain `manifest.tokenMappings` with the report so its exact token identities and CoinGecko price proxies stay visible beside the dataset hash. Select `execution: "contract_terms"` only to hypothetically replay the concrete trade terms. A standing contract bounds authority; it does not describe discretionary model choices. For a prompt whose trades are unresolved, use `execution: "triggers_only"` and present only trigger counts, timing and data limitations. Never describe contract-term returns as a prediction of what a discretionary agent would decide. --- # Notifications Fin tells your users when something they would want to know happens while they are not looking: an approval or a question waiting for them, an alert or report from one of their automations, money that moved, a problem with an automation, or fin's reply in a chat they left. For a user with the `proactive` feature on, fin also tells them what it noticed in their money: a fall, big news about a coin they hold, and a look at their week ([fin's notices](#fins-notices)). Each notification is about one thing, with its text ready to show, and records when the user read it. Your app shows them in two places: an inbox, read with the user's session, and a ping on the user's devices, which your server sends from a feed it reads with your partner key. Fin never sends an email, a text or a push itself, and a notification grants nothing: approving still happens on the approval card, with the user's own signature. ## Show the inbox Read the user's inbox with their session, through [List notifications](/api-reference/notifications/list): ```http GET /v1/users/{userId}/notifications?limit=20 Authorization: Bearer X-Api-Key: fin_… ``` ```jsonc { "data": [ { "id": "…", "kind": "approval", "category": "needs_you", "title": "fin needs your OK", "body": "Swap 100 USDC for NEAR", "withoutAmounts": { "title": "fin needs your OK", "body": "A request is waiting for your approval." }, "subject": { "type": "approval", "approvalId": "…", "conversationId": "…" }, "status": "waiting", "expiresAt": "2026-10-19T09:54:00.000Z", "createdAt": "2026-10-19T09:41:00.000Z", "readAt": null } ], "nextCursor": "…", "unreadCount": 3 } ``` - **Newest first.** Pass `nextCursor` back as `cursor` for older ones. `unread=true` lists only the unread, and `conversationId` only those about one conversation. - **`unreadCount`** is for a badge: every unread notification of the user's, whatever page you read. - **`title` and `body`** are plain text that Fin writes, with no links or markdown, and a token a chat card named by its whole mint reads shortened (`Use BONK, mint DezX…B263`). Show them as they are. `withoutAmounts` is the same notification without amounts or the user's own words, for a lock screen or anywhere the user asked you to hide them. - **`tokenId`**, on a trade, a filled order, a deposit or a withdrawal, is the token it is about, and on one of fin's notices the coin it is about: draw its icon beside the text. - **`tone`** says how it reads, to tint its icon: `needs_you` while it waits on the user, `problem` when something went wrong or fin noticed a fall in the user's money, `resolved` when an automation's problem is over, and `neutral` otherwise. - **`subject`** says what the notification is about. Open that thing's page when the user taps it: the approval or question in its conversation, the automation run, the agent's trade, the user's own swap, a Solana buy or sale, the limit order, the Polymarket order, the deposit, the withdrawal, the automation, or the conversation at fin's reply. | `subject.type` | Open | | --- | --- | | `trade` | [Get a trade](/api-reference/wallets/get-trade) with `tradeId` | | `swap` | [Get a swap](/api-reference/wallets/get-swap) with `swapId` | | `solana_trade` | a trade the user placed on the token's page: [Get a Solana trade](/api-reference/solana/get-trade) with `tradeId`; one the agent made: the `solana` item of [List activity](/api-reference/activity/list) whose `id` is `tradeId` | | `order` | [Get a limit order](/api-reference/wallets/get-order) with `orderId` | | `prediction_order` | [Get a prediction order](/api-reference/prediction/get-order) with `orderId` | | `story` | [Get a market story](/api-reference/market/stories-get) with `storyId` | | `asset` | your page for the coin `assetId` names, with the user's holding of it from [Get portfolio](/api-reference/portfolio/get) | | `week` | the inbox itself: the week's look says all it has to say | `subject.type` can grow too: open one you do not know as the inbox, never as a broken link. - **`status`** is there for an approval or a question: `waiting` while the user can still answer, with `expiresAt`; `expired` once it ran out; `done` once it was answered. An approval or question that stopped waiting counts as read. `waiting` also marks an `automation_attention` for an automation fin paused until its owner acts. It has no `expiresAt`, and reads `done`, and read, once they resume it, change it or delete it. - **`action`** is on that paused automation only, and says what moves it on: `add_funds` or `edit_automation`. Absent, the owner moves it on from the automation's page: by a choice, or by resuming it when its `waitingForOwner.action` is `resume`. - **`kind` and `category`** can grow. Show a notification of a kind you do not know by its `title` and `body`, and open its `subject` if you know its `type`. Financial figures may be absent when settlement receipts do not establish an actual amount. Show Fin's supplied text; never fill an unknown amount from the request, quote or a zero default. A notification that requires a monetary amount waits until suitable settlement evidence is available. Missing figures do not mean no money moved. | `category` | Kinds | | --- | --- | | `needs_you` | `approval`, `question`, and an `automation_attention` for an automation that waits for its owner | | `alerts_and_reports` | `automation_report` | | `money_moved` | `trade`, `order_filled`, `deposit`, `withdrawal` | | `automation_problems` | Every other `automation_attention` | | `replies` | `reply` | | `big_moves` | `holding_move` | | `big_news` | `market_story` | | `weekly_look` | `weekly_look` | Money that moved is told however it was started. A `trade` comes when a trade ends: one an automation made, one fin made in chat, the user's own swap, or a Solana buy or sale, the user's own on the token's page included; a sale of several coins under one approval is told once, as a sale of that many coins, with `tokenId` its first coin's. An `order_filled` comes once when part of a limit order or a Polymarket order first fills and once when all of it has. A `withdrawal` comes when one ends, and a `deposit` when one arrives or goes back. The categories are the switches to offer if your app lets users choose what pings them. Leave `big_moves`, `big_news` and `weekly_look` off until the user turns them on: they are fin's own notices, new to the user, and the inbox lists them either way. ## fin's notices With the `proactive` feature on for a user ([List the user's features](/api-reference/users/list-features) says whether it is), fin watches their money and records three notices of its own, from plain rules over prices, the market's stories and the user's holdings; no model writes them: - **`holding_move`** (`big_moves`): a coin worth at least $50 and 10% of the user's money fell far more than it usually does in a day (at least 8%, more for a coin that usually moves more), or their whole money fell 5% or more in a day. Its `subject` is the coin (`asset`). - **`market_story`** (`big_news`): a story at least six publishers carried in the last 12 hours is about a coin like that. Its `title` is the story's headline as the market desk titled it, plain and without links; `withoutAmounts` leaves it out. Its `subject` is the story (`story`). - **`weekly_look`** (`weekly_look`): from Monday 14:00 UTC, once a week, what price moves did to the user's money, with idle dollars in the agent wallet and one coin that is most of the money. Its `subject` is the week (`week`). Fin records at most one `holding_move` or `market_story` for a user in a day and three in a week, and never two stories about the same coin within 48 hours; the weekly look is outside those caps. Each of these carries **`options`**: up to three ways to act on it, best first, each with a `title`, a one-line `detail` and a `button` label. Show them where the user opens the notification, never in a push or on a lock screen, under a line saying they are options, not recommendations, and that doing nothing is fine. An option grants nothing; its `review` says what choosing it does: | `review.kind` | What choosing it does | | --- | --- | | `ask` | [Start a run](/api-reference/runs/start) with `question` as the user's own message. fin proposes, and the user approves in chat as always. | | `open` | Open your own form for `targetId`, filled in: `earn` is Earn, with `amount` to put in. | `options` is absent on every other notification. Ping a user's devices for these only once they have turned the category on, and hold a ping that would arrive at night on their device until morning. ## Mark them read When the user has seen the inbox, mark everything up to the newest notification they saw with [Mark notifications read](/api-reference/notifications/mark-read): ```http POST /v1/users/{userId}/notifications/read Authorization: Bearer X-Api-Key: fin_… { "through": "" } ``` That marks it and everything older, and leaves unread a notification that arrived since. To mark some, send `notificationIds` instead (up to 100). The answer is the notifications this call changed (the newest 100 at most) and the new `unreadCount`. A `through` request still marks every older notification even when more than 100 change; refresh the inbox to read their current state. Reading is shared: a notification marked read on one device is read on all of them. Marking again is safe and changes nothing, so the call takes no `Idempotency-Key`. ## Deliver pings from your server Read the feed with your partner key alone, every few seconds, from one place on your server, through [List notifications to deliver](/api-reference/partner/notifications): ```http GET /v1/partner/notifications?after=&limit=100 X-Api-Key: fin_… ``` ```jsonc { "data": [ { "id": "…", "userId": "user-7", "kind": "deposit", "title": "1,000 USDC arrived", "body": "In your wallet", "push": true, "…": "…" } ], "nextCursor": "…" } ``` - **Oldest first, every user of yours.** Each item names its user by your own `userId` for them. - **Keep `nextCursor`**, even from an empty page, and pass it back as `after`, including after a restart. Omit `after` only the first time. A notification takes its place in the feed once it is committed and its short wait has passed, so a cursor never skips one. - **`push: true`** means show it on the user's devices now. It is `false` when the user already saw it, or when its approval or question was answered or ran out before this feed read, even when its place was assigned earlier. An approval, a question or a reply waits a little before it takes its place (20 to 30 seconds), in case the user sees it in your app first; everything else takes its place at once. - **Skip what is stale.** After an outage, don't ping for an approval or question whose `expiresAt` has passed, or for anything long past; advance your cursor over them anyway. - **Respect the user's choices**: their category switches (fin's own notices start off), whether to show amounts (use `withoutAmounts` when they said no), and a device they are using right now, which already shows the inbox. Tell Fin's operators once your app delivers the feed: they turn on the `notifications` feature for your users, and fin then promises pings only on devices where they have turned notifications on. It must not imply permission is already granted or a push was delivered. Until then fin makes no such promise and says where a result will be instead. --- # Suggestions Fin reads each user's whole account in the background and suggests the moves worth making on it: an order to move, renew or cancel, an automation to pause, resume, change or end, and money to swap, protect with a sell line, put on a schedule, deposit or withdraw. Each suggestion carries the exact terms of its review, which Fin computed from the account. Suggestions are available to every user. The model decides what is worth suggesting, and often that is nothing. Fin checks every move it proposes before anyone sees it: the order, automation or holding is the user's own and in a state that allows the move, the amount fits what they hold, a schedule stays covered for four weeks, and a price sits on the right side of the market. Fin writes the title and fills in every figure of the reason from the account itself. A suggestion moves no money: the user makes each move through the routes that make it, where money still needs their approval. ## Read a page's suggestions ```http GET /v1/users/{userId}/suggestions?surface=orders&timeZone=Europe%2FLondon&country=GB&perpsAllowed=false X-Api-Key: fin_… Authorization: Bearer ``` | Query | What it is | | --- | --- | | `surface` | The page asking: `home` (the default), `orders`, `automations`, `swap`, `earn`, or one asset's page as `asset:` and its `assetId` from [Get balances](/api-reference/wallets/balances). Home gets every kind of move; a page gets the moves that belong on it. | | `timeZone` | The user's IANA time zone. Dates and run times read in it; without it they read in UTC and no suggestion starts a new schedule. | | `country` | The country the user is reading from, as your server resolved it. A move on a tokenized stock shows only where stocks are available; without a country, none shows. | | `perpsAllowed` | `true` when your app lets this user fund perpetuals where they are now; without it, no perps move shows. | Send all three with every read. They apply to that read only, and Fin never stores them. A read answers at once and never waits on the model: - `ready`: show `suggestions`, at most three, best first. With none, `calm.watching` counts the orders and automations Fin keeps an eye on, for a quiet line such as "Nothing needs you". When `updating` is `true`, something changed and Fin is reading the account again; what it shows still holds. - `thinking`: Fin is reading an account it has nothing saved for yet. Read again in a few seconds. - `failed`: Fin could not read the account. When `retryable` is `false`, the user's AI budget (`budget_exhausted`) or the hourly limit (`rate_limited`) stopped it, and trying again now changes nothing: say so and offer no Try again. When it is `true` (`model_unavailable`, `model_timeout` or `invalid_output`), a later read tries again. An answer Fin could not read is tried once more at once, so `invalid_output` means neither answer could be used; the page reads `thinking` while the second try runs. While a visible page shows `thinking`, or `updating` is `true`, read again every few seconds. ## When Fin reads the account again Fin keeps one set of suggestions per account and reads the account again when something a suggestion depends on changes: a holding's amount, an order or automation placed, filled, edited, paused or cancelled, a deposit under way, the user's deposit limit or one of their features. Prices alone never start a read. Each suggestion holds while the prices it uses stay within 5% of where they were; one that leaves that band is hidden and starts a read. A set lasts 24 hours, and Fin keeps the suggestions of anyone who read theirs in the last day current in the background, so most visits find them ready. ## Budget and limits Reading suggestions costs nothing. Each time Fin reads an account again, its one model call reserves a few cents from the user's AI budget before it is made, like a chat message, and settles what it cost; it counts toward your account's spend caps too. Fin reads an account at most once a minute, and its reads count toward the user's 30 an hour and 200 a day. When the budget or those limits stop a read, the page keeps the suggestions that still hold; with none left, it answers `failed` with `retryable: false`. These limits never answer `429` here. ## Show a suggestion | Field | What it is | | --- | --- | | `id` | The suggestion's id. The same move in a later read keeps it. | | `title` | The move, verb first, with its exact terms, written by Fin: "Move your NEAR buy to $4.80". | | `reason` | Why, in one sentence. Fin filled in every figure from the account. | | `review` | The terms the move's review draws, keyed by `kind`. | | `surfaces` | The pages it belongs on. | | `expiresAt` | When it is no longer served. | Every value in `review` is exact. An amount is `{ asset, amountRaw }`, with the asset's `assetId`, `symbol` and `decimals` and the amount in its smallest unit; dollars are decimal text such as `"4.80"`; a share is whole basis points; an instant is RFC 3339. The one figure the review lets the user adjust with − and + is `{ options, suggested }`: every value a step reaches, lowest first, at most 25, each with what follows from it, opening on `options[suggested]`. Draw the review from these values and step between options; compute nothing yourself. ## Open its review When the user opens a suggestion, check it again: ```http GET /v1/users/{userId}/suggestions/{suggestionId}/review?timeZone=Europe%2FLondon&country=GB ``` It answers the suggestion with fresh terms from the account as it is now. When it answers `409 suggestion_changed`, the suggestion no longer holds: the account or a price moved, the user set it aside, or it can't be made where the user is now. Say it changed since Fin suggested it, and read the page's suggestions again. ## Make the move | `review.kind` | How the user makes it | | --- | --- | | `swap` | [Get a swap quote](/api-reference/wallets/quote-swap) for the chosen amount, then [Swap tokens](/api-reference/wallets/swap). | | `limit_order` | [Prepare an order](/api-reference/wallets/prepare-order) with the chosen option's `order`, then [Place an order](/api-reference/wallets/place-order). | | `order_move` | Cancel the order, then prepare and place the chosen option's `order`, in [the order below](#move-or-renew-an-order). | | `order_cancel` | [Cancel the order](/api-reference/wallets/cancel-order). | | `automation_pause`, `automation_resume` | [Pause](/api-reference/automations/pause) or [Resume](/api-reference/automations/resume) the automation. | | `automation_end` | [Delete the automation](/api-reference/automations/delete). | | `deposit` | Your deposit flow, for the chosen amount: [Create a deposit](/api-reference/wallets/create-deposit). | | `withdraw` | [Get a withdrawal quote](/api-reference/wallets/quote-withdrawal), then [Withdraw funds](/api-reference/wallets/withdraw), to the user's own wallet: the one your app has connected. Fin names no destination. | | `recurring_buy`, `price_rule`, `summary`, `automation_change`, `perps_fund` | [Start a run](/api-reference/runs/start) asking the agent for it with the chosen terms, as the user's own message; the user approves it in chat. | | `ask` | [Start a run](/api-reference/runs/start) with `question` as the user's own message. | ### Move or renew an order The old order holds the funds the new one needs, and [Prepare an order](/api-reference/wallets/prepare-order) checks the agent wallet's balance, so prepare the new order only once the old one is cancelled and its funds are back: 1. Check the suggestion again with [Get a suggestion's review](/api-reference/suggestions/review). On `409 suggestion_changed`, say it changed since Fin suggested it. 2. Tell the user that nothing rests between the cancel and the new order, then [cancel the order](/api-reference/wallets/cancel-order). On `409 order_not_cancelable`, read the order: if it expired, the cancel is done, so go on; if it filled, stop and say so. 3. Wait until [Get an order](/api-reference/wallets/get-order) shows it ended and [Get balances](/api-reference/wallets/balances) shows its funds back, reading every few seconds. If it partly filled, less comes back: prepare with what came back, or check the suggestion again. 4. Prepare the chosen option's `order`. 5. Check the prepared terms against the option the user chose: the amount, the limit price, the least they receive and the expiry. 6. Have the user's wallet sign the authorization. 7. [Place the order](/api-reference/wallets/place-order) with its request key. On `409 order_changed` because the funds are not back yet, send the same request again once they are, while its signature holds; after that, prepare and sign again. At the order's own price (`current.limitPriceUsd`) this renews it, with a fresh expiry. ## Not now ```http POST /v1/users/{userId}/suggestions/{suggestionId}/dismiss ``` It answers `204`. Fin stops suggesting that kind of move on that order, automation or asset until it changes or seven days pass, and later reads leave it out. Sending it again changes nothing. With `@nearai/financial-agents-sdk`, these are `suggestions.list`, `suggestions.review` and `suggestions.dismiss`; see [the recipe](/sdk-recipes#show-suggestions-on-a-page). --- # Market briefs A market brief explains what part of the market did over the past day, and why, with the sources behind each reason. Ask about the whole crypto market, a chain, an asset, one chain's copy of an asset, a stock, or up to ten of these together. No user is involved: your partner key alone calls these routes, once an operator turns market briefs on for your key. Every figure in a brief is Fin's own. An asset's or a chain's price, change and usual daily move come from the prices Fin's market desk publishes. A stock's and one chain's copy of an asset come from Fin's own price records of the token traded, the trading venue's price. Market cap, volume, dominance and value locked come from the desk's market reads. The model writes the words, and Fin checks them before you see them: no figure, link or advice of their own, and every reason cites evidence returned during the research. Reasons are possible explanations, not proof of causality. `explained` describes the brief as a whole; use `research.coverage` to see what the search and explanation supported for each subject. ## Find the subjects ```http GET /v1/market/subjects?alias=usd-coin X-Api-Key: fin_… ``` | Subject | What it is | Example | | --- | --- | --- | | `market` | the whole crypto market | `market` | | `chain:` | a chain and its ecosystem | `chain:solana` | | `asset:` | an asset across every chain | `asset:usdc` | | `asset:@` | that asset's copy on one chain | `asset:usdc@solana` | | `stock:` | a U.S. stock or ETF | `stock:NVDA` | Subject ids are Fin's own. Pass `alias` with a CoinGecko id, a symbol, a contract address or a 1Click asset id to find the subjects it names, or `kind` to list one kind. An asset spans its listed chain copies, and its price is the market desk's USD price of its one CoinGecko asset rather than a blend across chains: `asset:near` is priced as wrapped NEAR, and `chain:near` shares its native coin's price. A copy on one chain, such as `asset:usdc@solana`, is measured from its own token, so a bridged copy that loses its peg shows its own move. A stock uses its reviewed tokenized reference. A price metric's provenance names the CoinGecko asset, and for a copy or a stock the reference token measured. The usual daily move needs at least twenty daily moves in the past thirty days; with fewer, it and `magnitude` are null. ## Create a brief ```http POST /v1/market/briefs X-Api-Key: fin_… Idempotency-Key: 6f1c2a7e-… { "scope": ["chain:solana", "asset:sol"], "window": "24h", "mode": "news" } ``` - **`mode: "news"`** researches the requested subjects even when their prices barely moved. Use it when a reader opens news or asks what happened to an asset. Adding `market` is not necessary to request news for one asset. - **`mode: "auto"`**, the default when omitted, may answer `200` at once with `status: ready` when every subject barely moved: Fin's own words and figures, no research and no model cost. - **A researched scope** answers `202` with `status: generating`. Read it with [Get a market brief](/api-reference/market/briefs-get) after `retryAfterSeconds` until it is `ready` or `failed`. The wait depends on the research and checks required. The same key with the same request returns the same job; omitted mode and `auto` are equivalent. Changing scope, window or effective mode under that key is refused `409 request_key_conflict`. Each researched brief uses model runs your partner owns: it is charged to your partner's AI usage, counts toward your partner's day and month spend caps and active-run limit like every other run of yours, and the job's `costCents` says what it cost once it finished. Partner usage reports it in `partnerRunTotals`. ## Read a brief ```jsonc { "headline": "Solana falls after its network halted", "summary": "Solana dropped as validators stopped producing blocks.", "explained": true, "moves": [ { "subject": "asset:sol", "magnitude": "large", "metrics": [{ "name": "price", "value": "88", "changePct": "-12", "asOf": "…", "benchmark": { "subject": "asset:btc", "changePct": "-1" } }] } ], "drivers": [{ "text": "Validators halted block production after a consensus bug.", "subjects": ["asset:sol", "chain:solana"], "sourceIds": ["src_1"] }], "sources": [{ "id": "src_1", "title": "…", "publisher": "coindesk.com", "url": "…", "publishedAt": "…" }] } ``` - `magnitude` compares the 24-hour price move with the subject's usual daily move: `quiet`, `notable` or `large`. A move under a quarter of a percent is always `quiet`, so a stablecoin's daily wiggle is no news, while its slip to 0.996 is. - `metrics[].name` can grow: show the names you know and skip the rest. - `research.performed: false` with `skipReason: "quiet"` means no news search ran. Empty sources here do not mean that no news exists. Per-subject `searchStatus` distinguishes `not_searched`, `complete`, `partial` and `unavailable`; `complete` means the planned searches finished, not that every possible publisher was searched. `explanationStatus` separately distinguishes a `possible_driver`, `context_only` and an `unexplained` move. `sourceIds` names the supporting cited sources. A complete search can still leave the move unexplained. The single correction receives feedback for rejected fields and is independently reviewed again; supported context is not automatically approved for publication. `ready` can include `partial` or `unavailable` research with a cautious abstention; it means the checked pipeline finished, not that news retrieval succeeded. Surface that coverage to readers rather than presenting an empty source list as proof that no relevant news exists. - Each driver needs supporting official, permitted or newsroom reporting. Unreviewed items and press releases alone are leads, so Fin does not publish their claims as drivers. Publication time does not establish event time: a recent article about an older event can provide context, but cannot by itself establish a current explanation. The prompt revision is recorded in `pipelineVersion`; earlier jobs retain their recorded revision. - A metric's optional `unit` is `usd` or `percent`. Price, volume, market cap and TVL are USD; dominance and `changePct` are percentages. Negative changes are declines. `market` measures total crypto capitalization and BTC dominance, while BTC price is a separate asset and benchmark. - `provenance` names the provider and reference identity. Its `comparison.start` and `end` carry the exact prices and observation times used for a calculated return; these endpoints can span slightly more or less than 24 hours. A provider-reported change has no reconstructed endpoints; its reported trailing period does not create exact observations at the job's window boundaries. A benchmark can carry its own provenance because its observation times may differ. - `asOf` and `generatedAt` serve different purposes. `provenance.observedAt` is the provider's timestamp, or null if unavailable. `asOfBasis` tells whether `asOf` is a provider observation, retrieval time or generation time. A fresh generation or cache read does not refresh an old observation. Price facts are captured when requested; research metrics can be read later. The narrative review receives the compiled research metrics as well as the captured price facts, so a missing asset-style price does not hide an available market-wide level or change. - Research/provenance fields may be absent on older jobs. A missing value remains unavailable; it is never evidence for zero movement, zero volume or no relevant news. Source publishers may be null, so retain a fallback label when rendering citations. - Fin keeps no cache and serves each job only to the key that created it. Cache a brief on your side, keyed by its normalized `scope`, `window` and effective `mode`. Share creation keys and pending state across replicas if you need duplicate-cost protection across restarts. Reuse the original creation key after transport uncertainty; starting a new key can incur another model cost. ## Show it Label a brief as written by AI, show its sources beside it, and say that it is not investment advice. ## When a brief cannot be made | Answer | Why | | --- | --- | | `400 scope_invalid` | A subject is not a subject id, or appears twice. | | `404 subject_unsupported` | A subject is not one market briefs cover. | | `403 market_briefs_disabled` | Market briefs are not turned on for your key. | | `429 briefs_busy` | Your partner is at its active-run limit; retry after `Retry-After`. | | `429 budget_exhausted` | Your partner's AI budget is used up until the next day or month. | | `failed` with `generation_failed` | The brief could not be completed; consult optional failure details before retrying. | | `failed` with `brief_invalid` | The research produced words that failed Fin's checks twice. | Optional `failure.details` contains a safe `stage`, `reason` and `retryable` flag. It never contains provider error prose. Stages are `admission`, `research`, `synthesis`, `validation` or `deadline`; reasons are `unavailable`, `invalid_output`, `budget_exhausted` or `deadline_exceeded`. A deliberate retry after a terminal failure uses a new Idempotency-Key and may incur another cost. Reusing the old key still returns its original failed job. Do not automatically create another job after a lost response or while the first job is generating. ## Evidence and bounded correction Fin searches each canonical news identity within the job's absolute window. News identity and price reference identity can differ: NEAR Protocol research does not search only for wNEAR. A subject search makes at most two provider searches and two shortlisted content lookups. Provider raw content is relayed only for reviewed excerpt-permitted publishers; other items remain `title_only`. This is provider-relayed evidence, not a claim that Fin independently opened an original article. Sources retain `publishedAtBasis`, `retrievedAt`, `eventAt`, `sourceKind`, `evidenceLevel` and a bounded permitted `excerpt` when available. Unknown event time remains null. An independent, tool-free model review evaluates the headline, summary and every driver against committed passages. `evidence` on a brief and driver carries exact short quote witnesses. Driver `classification` separates context from qualified possible drivers; `eventAt` requires an actual source-supported event inside the window. A publication timestamp alone is insufficient. Exact quotes constrain this assistive review but cannot prove semantic truth or market causality. When there are no supported drivers, Fin uses cautious server-written abstention text. The public limits remain headline 120, summary 600 and driver 300 JavaScript string code units. A completed candidate that exceeds them can receive one tool-free correction against its original facts and evidence; Fin does not truncate the words or run the research again. The evidence review and correction both consume partner model usage, included in `costCents`. Unknown dispatched accounting is reported as null rather than zero. The job has a thirty-minute recovery deadline; this bounds job recovery, not promised response time. Work already admitted retains its normal run deadline and may settle later; an unknown cost stays null. Reuse the same key after a transport failure. --- # Market news Market news is what the crypto market is doing now, as Fin follows it: the stories the market is telling, the latest articles from reviewed publishers, the moves Fin spots as they happen, and where money is in the market. It is public market data, the same for every user, so your partner key alone reads it: no user session and no feature to turn on. Every route here only reads, and reading costs no AI usage; your partner rate limit applies. A news page takes four calls, and a story page one. ## Stories ```http GET /v1/market/stories?evidence=reported&limit=50 X-Api-Key: fin_… ``` A story is a few sentences on something happening in the market, written from the articles and the market figures behind it. The list is most recently confirmed first. - `topic` is what the story is about, as a reader would file it, one of `markets`, `funds`, `regulation`, `legal`, `security`, `governance`, `people`, `deals`, `funding`, `launches`, `networks`, `supply`, `stablecoins`, `tokenization`, `economy`, `ai`, `predictions`, `sports`, `memecoins`, `defi`, `wallets` and `data`; the reference says what each covers. Fin names it each time it writes the story. Show a story by it when nothing it names has a logo of its own; it is null for a story last written before topics. - `status` is `new`, `rising` (gathering coverage), `steady` or `fading`. - `evidence` is how well it is backed, strongest first: `measured` (a market figure it cites moved), `corroborated` (three publishers, or two with an official source), `reported` (an official or newsroom source, or two publishers) and `unconfirmed` (one unreviewed source). - `updatedAt` is when a new source or figure last confirmed it; `firstSeenAt` when Fin first saw it. - `subjects` are what it is about, each with its `id`, `kind`, `name` and ticker (`symbol`), and the listings the desk follows it by: `coingeckoId`, what you read its price history and logo with from CoinGecko (a coin's `bitcoin`, a venue's exchange `binance`, a sector's category `layer-1`); `hyperliquidCoin` (`BTC`), the coin its Hyperliquid market trades as; and `defillamaId`, what DefiLlama lists it as (a venue's or launchpad's protocol `uniswap-v3`, a chain's name `Ethereum`), which its logo is found by. Each is null when it has none. - `sources` are its three newest articles, and `sourceCount` how many it rests on. Most stories of a day rest on one unreviewed source, so pass `evidence: reported` for a page people read; `evidence` keeps that grade and every stronger one. `subject` keeps the stories about one subject: `asset:btc`, `stock:NVDA`, `chain:solana`, `prediction:` or `market`. A story is rewritten as its coverage grows, and its figures read the market as it is when you ask, so read the list again rather than keeping a story for long. A story whose figures can't be read right now is left out until it is next written, so a page can hold fewer stories than `limit` while `nextCursor` is set: keep paging until `nextCursor` is null. ## One story ```http GET /v1/market/stories/{storyId} X-Api-Key: fin_… ``` The story with every article it rests on, newest first, and two more lists: - `figures`: each market figure the story states, as it reads now. `label` says what it is in plain words (`Price`, `Yes odds`, `Crypto market cap`), `value` and `unit` what it is now, and `changePct` how it changed over `window`. - `moves`: what Fin spotted moving on the story's coins, stocks and markets since the story began, newest first, one line per market and kind, as [List market moves](/api-reference/market/moves-list) answers them. A story Fin no longer shows, because its sources were withdrawn or its figures can no longer be read, answers `404 story_not_found`: take it off your page. ## Headlines ```http GET /v1/market/headlines?limit=30 X-Api-Key: fin_… ``` The latest articles from reviewed newsrooms and official sources, newest first, each with its `publisher`, `headline`, `url`, `publishedAt`, a short `excerpt` where the publisher's licence allows one, and the coins and stocks its headline names (`subjects`, in the order it names them). Posts, project announcements and unreviewed sites are left out, and so is an article Fin found only to answer one user's question. An undated article stands at when Fin found it. `subject` keeps the articles naming one coin or stock among the newest 300: recent coverage, not an archive. ## Moves ```http GET /v1/market/moves?limit=20 X-Api-Key: fin_… ``` What moved in the market, newest first, each as one plain sentence: | `kind` | What moved | `text` | | --- | --- | --- | | `price` | a coin's price | `WIF up 18.4% in 4 hours` | | `market` | the market as a whole | `Crypto market cap down 10.5% over 7 days` | | `odds` | a prediction market's Yes odds | `“Will Bitcoin dip to $71,000 on November 12?” Yes down 13.5 points in 15 minutes` | | `resolved` | a prediction market resolving | `“Will the price of Bitcoin be between $72,000 and $74,000 on November 12?” resolved` | | `volume` | a chain's, venue's or launchpad's volume or fees | `Stonks launchpad volume down 31.6% over 30 days` | | `share` | a launchpad's share of launchpad volume | `pump.fun's share of launchpad volume down 11.6 points over 7 days` | | `leader` | a new leader of a leaderboard | `pump.fun takes the lead from Montra in 7-day launchpad volume` | | `entrant` | a newcomer to a top list | `LaunchLab enters the top 5 launchpads by 7-day volume at #3` | `changePct` (a price, market or volume move) or `changePoints` (odds and shares) is the move's exact size and `window` its span, for drawing your own label. `subjects` are what moved, the one the sentence is about first. Each market has one line per kind, and each leaderboard one line of lead changes: a newer move on the same line replaces the older one, so a prediction market whose odds swing every quarter hour stays one line, and a lead that changes back leaves only the latest change. Narrow the list with `kind` or `subject` (the latest of each line among the moves naming it), and read the first page again to follow it: a newer move has a larger `id`. A move Fin can't put into words is left out, so a page can hold fewer moves than `limit` while `nextCursor` is set: keep paging until `nextCursor` is null. ## Money flows ```http GET /v1/market/flows X-Api-Key: fin_… ``` Six market-wide figures, each with its value in US dollars and its change over a day, a week and a month: the crypto market cap, alt trading volume, perps open interest, stablecoin supply, DEX trading volume and launchpad volume. A volume's `valueUsd` is the latest day's total, and its change compares each window with the one before; a level's change compares the window's end with its start. A figure Fin doesn't have right now is left out, and a change without enough history is null. ## A news page 1. Stories with `evidence: reported`, up to 100: keep those updated in the last two days and order them as your page needs, for example the best backed and most active first. 2. Headlines: the newest 30. 3. Moves: the newest 20. 4. Flows: all of them. Read them again every minute or so while the page is open, and open a story with [Get a market story](/api-reference/market/stories-get). Label the stories as written by AI, show their sources beside them, and say the news is not investment advice. ## Paging and refusals The lists take `limit` (up to 100) and `cursor`. Pass `nextCursor` back unchanged. A stories or headlines cursor is good only with the filters it came with; a moves cursor is a place in the list, good with any filters. A stories or moves page can hold fewer rows than `limit` while `nextCursor` is set, so keep paging until `nextCursor` is null. | Answer | Why | | --- | --- | | `400 invalid_cursor` | The cursor is not one this list issued, or a stories or headlines cursor came with other filters. | | `404 story_not_found` | No story with this id is current. | --- # Usage and limits All your API keys share one account: one usage record and one set of limits. Adding keys or users doesn't add capacity. These limits cover requests and AI usage; they have nothing to do with the money in users' wallets. ## Read your usage ```http GET /v1/partner/usage?periodKind=day&periodStart=2026-09-22&limit=100 X-Api-Key: fin_… ``` This needs only your API key. For a month, send `periodKind=month` and the month's first day. The answer has `totals`, a page of rows in `data`, `nextCursor` and `asOf`. Keep passing `nextCursor` back as `cursor` to export every row. A period that is still open keeps changing, so treat an export as a report, not an invoice. `totals` includes model calls for your users' runs, your partner's own runs, suggestions and voice transcriptions. `suggestionTotals` gives the suggestion portion of those same totals, `voiceTotals` the transcription portion, and `partnerRunTotals` the portion of runs Fin makes for your partner itself, such as market briefs; older servers omit these fields. The paginated `data` contains your users' run calls only, because a suggestion set and a transcription have no run and a partner run has no user. To reconcile a complete export with total inference usage, include the suggestion, voice and partner-run totals once each, not once per page. Costs are whole cents, so each transcription counts as one cent however short it is: ten thousand of them come to $100. Each row is one run's AI model call: which user, agent and run made it, and what it cost. Costs are strings of whole US cents: - `knownCostCents`: calls whose cost is final. - `reservedCents`: the maximum still held for calls whose final cost isn't known yet. - `uncertainReservedCents`: the part of `reservedCents` for calls that reached the provider but never reported back. It is already included in `reservedCents`; don't add it twice. - A row with `actualCostCents: null` has no final cost yet. `null` never means zero. Rows never contain prompts, messages or amounts of money. A call is always charged to the day and month it was made in, even if its cost is settled later. ## Your limits [Get your rate limits](/api-reference/partner/quotas) returns your limits, what is in use now, and the spend caps for the current day and month. Its usage includes runs, suggestions and voice transcriptions. Use `periods[].capCents` for the effective allowance of an open UTC day or month, including any audited operator adjustment. `limits.dayCapCents` and `limits.monthCapCents` configure future periods and can differ from the caps of periods already open. | Limit | Default | | --- | --- | | Requests | 600 a minute, across all keys | | Runs in progress | 32 at once (paused runs don't count) | | Open event streams | 32 at once, 4 per user | | AI spend | $100 a day, $1,000 a month | Each user also has their own AI usage budget; see [Get AI usage budget](/api-reference/budgets/get). Each time fin reads a user's account again for [suggestions](/suggestions), it spends from it like a chat message. Those reads count toward the user's 30 an hour and 200 a day, and an account is read at most once a minute; reading suggestions Fin already made costs nothing and counts toward neither. When the budget or those limits stop a read of the account, List suggestions keeps serving what still holds, and with nothing left it answers `failed` with `retryable: false` rather than an error. When a limit is reached: | Answer | What to do | | --- | --- | | `429 partner_request_capacity` | Wait for `Retry-After`, then retry. | | `429 partner_run_capacity` | Wait for `Retry-After`, then retry with the same `Idempotency-Key`. | | `429 stream_capacity` | Close streams you don't need, or wait for `Retry-After`. | | `429 budget_exhausted` | The user's AI budget is used up (or frozen by an operator) until the next day or month. | | A failed run whose `failure.code` names a budget or spend limit | A limit had no room for the run's next model request. Tell the user which one, not that the model failed, and read the run's trades before they ask again. The codes are in [Budgets and limits](/concepts#budgets-and-limits). | A stream holds its slot while it is open. If your process dies without closing it, the slot frees itself within about a minute. ## Changing limits Your API key can read limits but not change them; ask your deployment operator. New request, run and stream limits apply straight away to new work; running work finishes. A new daily or monthly spend cap applies from the next day or month unless the operator explicitly applies it to the current UTC periods too. That audited adjustment takes effect immediately for new model reservations and preserves all recorded spend and outstanding reservations. --- # Building with the packages Two packages cover most of an integration: a typed client for your server, and Fin's blocks for your React chat. Use either one alone, or both together. - [**Server SDK**](/sdk-quickstart) — `@nearai/financial-agents-sdk`: every operation, typed, with sessions, retries and live streams handled. - [**React components**](/react-quickstart) — `@nearai/financial-agents-react`: Fin's replies, approvals, questions and result cards, inside your own chat. > [!NOTE] > The packages are not on npm yet. They publish with their first release. ## How they fit Your API key and your users' sessions stay on your server. The SDK talks to Fin, your server relays the conversation, and the React package draws it. 1. **Your server** creates the user, opens their session after your own sign-in, and starts a run for each message: `users.create`, `users.createSession`, `runs.start`. 2. **Your server** follows the conversation with `events.stream` and relays each event to the page. 3. **Your page** folds the events with `threadReducer`, and draws Fin's entries with `FinEntry` beside your own message bubbles. 4. **The user** decides an approval or answers a question; your server sends it with `approvals.approve`, `approvals.deny` or `questions.answer`. Neither package needs the other: use the SDK under your own interface, or the components over data your server reads by HTTP. ## Install ```sh npm install @nearai/financial-agents-sdk # on your server npm install @nearai/financial-agents-react @base-ui/react # in your React app ``` ## Requirements | | `@nearai/financial-agents-sdk` | `@nearai/financial-agents-react` | | --- | --- | --- | | Runs on | Your server: Node 20+, Bun, Deno, edge runtimes | The browser, and your server for server rendering | | Peer dependencies | None | React 19, `react-dom` 19, `@base-ui/react` 1.3+ | | TypeScript | 5.4+ | 5.4+ | | Entry points | `@nearai/financial-agents-sdk` | `@nearai/financial-agents-react`, `/model`, `/fixtures`, `/styles.css` | ## Money needs the user's signature Creating the agent wallet, withdrawing and approving a trade each carry the user's wallet signature of the exact message Fin issued. Fin verifies it on arrival and again before anything is signed. > [!IMPORTANT] > Before your page asks the user to sign, check the message with the SDK's `isAuthorizationFor`, > so the user only ever signs a Fin authorization of their own. The > [recipe](/sdk-recipes#money-needs-the-user-s-signature) shows how. The approval card shows the exact terms of the contract Fin derived, never the model's words. A contract the card cannot read offers only Cancel: nobody approves terms they were not shown. ## Next steps - [**SDK quickstart**](/sdk-quickstart) — Create a user, open a session and stream a reply. - [**React quickstart**](/react-quickstart) — Draw a Fin conversation in your own chat. - [**SDK recipes**](/sdk-recipes) — Relaying, approvals, funding, withdrawals and errors. - [**Theming**](/react-theming) — Your palette, your classes, or your own markup. - [**SDK reference**](/sdk-reference) — Every method, option, error and type. - [**Components reference**](/react-components) — Every block, its props and its parts. --- # Packages quick reference The calls you use most from both packages, on one page. ## Server SDK `fin` is the client from `createFinClient`, and `user` is `fin.user({ userId, token })`. [Recipes](/sdk-recipes) explain each task; the [reference](/sdk-reference) lists every method. ### Users and sessions | Task | Call | | --- | --- | | Create the client | `createFinClient({ baseUrl, apiKey })` | | Create a user, once | `fin.users.create({ userId, name })` | | Sign in after your own login | `fin.users.createSession(userId, { controller })` | | Sign in with the user's wallet | `fin.users.sessionChallenge(userId, { controller, origin })`, then `fin.users.createSession(userId, { challengeId, signature })` | | Sign in and create the wallet with one signature | `fin.users.sessionChallenge(userId, { controller, origin, createWallet: true })`, `fin.users.createSession(…)`, then `user.wallets.create({ signIn: { challengeId, signature } })` when `createsWallet` | | Open the account with a passkey your login just created | `fin.users.createSession(userId, { controller, createWallet: true })`, then `user.wallets.create({})` when `createsWallet` | | Act as the user | `fin.user({ userId, token })` | | Check a session | `fin.users.me({ token })` | | Sign out | `fin.users.revokeSession({ userId, sessionId, token })` | ### Conversations and runs | Task | Call | | --- | --- | | Find the conversation | `user.conversations.main()` | | Send a message | `user.runs.start({ conversationId, text, context }, { idempotencyKey })` | | Follow it live | `for await (const event of user.events.stream(conversationId, { signal }))` | | Read its history | `paginate((cursor) => user.events.list(conversationId, cursor ? { cursor } : {}))` | | Stop a run | `user.runs.cancel(runId)` | | Send feedback on a reply | `user.runs.sendFeedback(runId, { rating: "down", reason: "wrong" })` once the run has ended; delete it with `user.runs.deleteFeedback(runId)` | ### Approvals and questions | Task | Call | | --- | --- | | Check a message before the user signs | `isAuthorizationFor(await fin.users.me({ token }), audience, toSign)` | | Approve | `user.approvals.approve(approvalId, { authorization })` | | Deny | `user.approvals.deny(approvalId, {})` | | Answer a question | `user.questions.answer(questionId, { kind: "answers", answers }, { idempotencyKey })` | ### Agent wallet and automations | Task | Call | | --- | --- | | Create the wallet | `user.wallets.get()` for `creation`, then `user.wallets.create({ authorization })`, or `{ signIn }` after an account-opening sign-in, or `{}` from a session that opened the account with a new passkey | | Read balances | `user.wallets.balances()` | | Read everything it owns | `user.portfolio.get()` | | Chart its value | `user.portfolio.history({ range: "1W" })` | | Price a deposit | `user.wallets.quoteDeposit({ rail, network, assetId, amountRaw, maxValueLossBps })` | | Fund it | `user.wallets.createDeposit({ terms }, { idempotencyKey })` | | Withdraw | `user.wallets.quoteWithdrawal(request)`, then `user.wallets.withdraw({ terms, authorization }, { idempotencyKey: quote.requestKey })` | | Swap | `user.wallets.quoteSwap(request)`, then `user.wallets.swap({ terms, authorization }, { idempotencyKey: quote.requestKey })` | | Place a limit order | `user.wallets.prepareOrder(request)`, then `user.wallets.placeOrder({ terms, authorization }, { idempotencyKey: prepared.requestKey })` | | Pause or resume an automation | `user.automations.pause(id)`, `user.automations.resume(id)` | | Handle a refusal | `if (error instanceof FinApiError) error.reason` | ## React components [The quickstart](/react-quickstart) puts these together; the [components](/react-components) and [view models](/react-model) references list everything. ### Set up | Task | Use | | --- | --- | | Load the styles | `import "@nearai/financial-agents-react/styles.css"` | | Order the layers in a Tailwind app | `@layer theme, base, fin, components, utilities;` above `@import "tailwindcss"` | | Configure links and routes | `` | | Use your own token list | ``, or wrap `DEFAULT_TOKENS` | ### Draw the conversation | Task | Use | | --- | --- | | Fold the events | `useReducer(threadReducer, initialThread)`, then `dispatch(event)` | | List what to draw | `transcriptEntries(thread)`, keyed by `entryKey(entry)` | | Draw the agent's text | `` with `replyContext(thread.items)` | | Draw live text | `` | | Draw everything that is Fin's | `` | | Keep one approval open at a time | wrap the transcript in `` | | Offer the suggested replies | `` | | Let the cards carry the facts | send `RENDERED_CARDS` as `context.renders` | | Show cards as the agent finds what it needs | add `show` (or `placement`) to `context.renders`, draw `threadTurns(thread)` | | Report the user's country | send `context.country` from your server's edge geolocation with every message; see [Tokenized stocks](/concepts#tokenized-stocks) for country and purchase restrictions | ### Style and test | Task | Use | | --- | --- | | Retheme | `--fin-*` variables on `:root` | | Restyle one block | `className`, and `classNames` for its parts | | Restyle every button | CSS on `[data-fin-ui="button"][data-fin-variant="primary"]` | | Draw your own approval | `approvalContent(approval)` | | Show a token | ``, or `` | | Draw states in stories and tests | `foldFixture("approvalPending")`, `oneShotApproval(contract)` from `/fixtures` | --- # SDK quickstart Create a user, open their session and stream the agent's reply from a script on your server. It takes about fifteen minutes and needs no wallet or funds. ## Before you begin - **A runtime with `fetch`**: Node 20 or later, Bun or Deno. - **An API URL and an API key** from your deployment operator. The key never leaves your server. - **TypeScript 5.4 or later**, if you type-check. The SDK ships its own types. > [!NOTE] > The packages are not on npm yet. They publish with their first release. ## 1. Install ```sh npm install @nearai/financial-agents-sdk ``` ## 2. Create the client Create one client and share it across your server. ```ts title="fin.ts" import { createFinClient } from "@nearai/financial-agents-sdk"; export const fin = createFinClient({ baseUrl: process.env.FIN_BASE_URL ?? "https://api.example.test", apiKey: process.env.FIN_API_KEY ?? "", }); ``` ## 3. Create the user `userId` is your own id for the user: letters, digits, `.`, `_`, `:` and `-`, never an email address. Creating a user again returns the same user. ```ts const created = await fin.users.create({ userId: "customer-123", name: "Example user" }); console.log(created.agentId); // the user's agent ``` ## 4. Open a session After your own login succeeds, vouch for the user by naming the wallet they signed in with. They sign nothing here. ```ts const { token } = await fin.users.createSession("customer-123", { controller: { kind: "evm", chainId: 1, address: "0x0000000000000000000000000000000000000001" }, }); ``` - The first session registers this wallet for good. It signs anything that moves money. - A session lasts one hour. When a call rejects with `credential_expired`, open a new one. - NEAR, Solana, Stellar, TON and Tron wallets and passkeys work too: see [Authentication](/authentication). Without a login of your own, use [wallet sign-in](/sdk-recipes#sign-users-in). > [!WARNING] > Keep `token` on your server. Never put it in a page, a URL or browser storage. ## 5. Send a message Every user has a main conversation. Send the message there: ```ts const user = fin.user({ userId: "customer-123", token }); const conversation = await user.conversations.main(); const run = await user.runs.start( { conversationId: conversation.id, text: "Say hello in one sentence.", profile: { tools: [] }, context: { timeZone: "America/New_York" }, }, { idempotencyKey: crypto.randomUUID() }, ); ``` | Field | Purpose | | --- | --- | | `idempotencyKey` | Made once per message. A retry with the same key returns the same run. | | `profile.tools` | `[]` turns tools off for this run. Leave `profile` out to allow every enabled tool. | | `context.timeZone` | The user's time zone, so "9am" means their 9am. Send it with every message. | | `context.country` | The user's uppercase two-letter country code from your server's edge geolocation, never the browser. Send it with every message; omit it when unavailable. | Tokenized-stock purchases require a country outside the United States and Canada and an operator-enabled `tokenized_stocks` flag. Once held, these assets can only be sold, never withdrawn or sent; see [Tokenized stocks](/concepts#tokenized-stocks) for the country rule when selling. ## 6. Stream the reply `events.stream` replays the conversation, then follows it live. Skip to your run, print its text as it is written, and stop when it ends: ```ts const stop = new AbortController(); let ours = false; for await (const event of user.events.stream(conversation.id, { signal: stop.signal })) { if (event.type === "run.started") ours = event.payload.runId === run.id; if (!ours) continue; if (event.type === "agent.text_delta") process.stdout.write(event.payload.text); if (event.type === "run.ended") stop.abort(); } ``` `agent.text_delta` is live text and is never replayed; the saved `agent.entry` replaces it. The stream reconnects by itself and resumes after the last saved event. ## The complete script ```ts title="quickstart.ts" import { createFinClient, FinApiError } from "@nearai/financial-agents-sdk"; const fin = createFinClient({ baseUrl: process.env.FIN_BASE_URL ?? "https://api.example.test", apiKey: process.env.FIN_API_KEY ?? "", }); try { await fin.users.create({ userId: "customer-123", name: "Example user" }); const { token } = await fin.users.createSession("customer-123", { controller: { kind: "evm", chainId: 1, address: "0x0000000000000000000000000000000000000001" }, }); const user = fin.user({ userId: "customer-123", token }); const conversation = await user.conversations.main(); const run = await user.runs.start( { conversationId: conversation.id, text: "Say hello in one sentence.", profile: { tools: [] } }, { idempotencyKey: crypto.randomUUID() }, ); const stop = new AbortController(); let ours = false; for await (const event of user.events.stream(conversation.id, { signal: stop.signal })) { if (event.type === "run.started") ours = event.payload.runId === run.id; if (!ours) continue; if (event.type === "agent.text_delta") process.stdout.write(event.payload.text); if (event.type === "run.ended") stop.abort(); } } catch (error) { // Every refusal is a FinApiError: quote its requestId when you report it. if (error instanceof FinApiError) console.error(error.status, error.reason, error.requestId); else throw error; } ``` ## Next steps - [**SDK recipes**](/sdk-recipes) — Relay to the browser, approve money actions, fund and withdraw. - [**React quickstart**](/react-quickstart) — Draw the conversation with Fin's blocks. - [**SDK reference**](/sdk-reference) — Every method, option, error and type. --- # SDK recipes Short answers to what your server does with `@nearai/financial-agents-sdk`. Each assumes `fin`, the client from the [SDK quickstart](/sdk-quickstart), and `user = fin.user({ userId, token })` for the signed-in user. ## Sign users in ### With your own login After your login succeeds, vouch for the user with your API key, naming the wallet or passkey your login verified. The user signs nothing more. ```ts const { token, session } = await fin.users.createSession(userId, { controller: { kind: "evm", chainId: 1, address: "0x0000000000000000000000000000000000000001" }, }); ``` Keep `token` beside your own session, on your server. Vouch again when a call rejects with `credential_expired`. ### With the user's wallet Without a login of your own, the user signs Fin's challenge, from the origin you registered: ```ts const challenge = await fin.users.sessionChallenge(userId, { controller: { kind: "evm", chainId: 1, address: "0x0000000000000000000000000000000000000001" }, origin: "https://wallet.example.test", }); // The page has the wallet sign challenge.message exactly as returned, and sends back the signature. const { token } = await fin.users.createSession(userId, { challengeId: challenge.challengeId, signature: { kind: "evm", signature: walletSignature }, }); ``` The challenge expires within five minutes. A NEAR wallet signs it with `challenge.recipient`. > [!NOTE] > The user's first session fixes their wallet or passkey for good. Later sessions must name the > same one. ### Open the account in the same signature Ask for `createWallet`, and a user with no agent wallet signs once: the signature that signs them in also creates the wallet. ```ts const opening = await fin.users.sessionChallenge(userId, { controller: { kind: "evm", chainId: 1, address: "0x0000000000000000000000000000000000000001" }, origin: "https://wallet.example.test", createWallet: true, }); // The page has the wallet sign opening.message exactly as returned. const signature = { kind: "evm" as const, signature: walletSignature }; const session = await fin.users.createSession(userId, { challengeId: opening.challengeId, signature, }); if (opening.createsWallet) await fin .user({ userId, token: session.token }) .wallets.create({ signIn: { challengeId: opening.challengeId, signature } }); ``` Send it within the challenge's five minutes. A user who already has a wallet gets the plain sign-in message, with `createsWallet: false`. ### Open the account with a passkey the user just created Creating a passkey signs nothing, so a passkey sign-up would otherwise take a second confirmation. When your own login just created and verified the passkey, vouch for it with `createWallet`: the session that registers it creates the wallet with nothing signed. ```ts // The passkey your login just created, as its verified registration gave it. const passkey = { kind: "webauthn" as const, credentialId: "q2W8eHn0SPuWxFJjWm1RfA", publicKey: "pQECAyYgASFYIK…", rpId: "wallet.example.test", origin: "https://wallet.example.test", }; const session = await fin.users.createSession(userId, { controller: passkey, createWallet: true }); if (session.createsWallet) await fin.user({ userId, token: session.token }).wallets.create({}); ``` Create the wallet within 270 seconds of creating the session. A wallet, or a passkey the user signed in with before, gets `createsWallet: false`, and its creation is signed. ### Check a session, and sign out ```ts const me = await fin.users.me({ token }); await fin.users.revokeSession({ userId: me.userId, sessionId: me.sessionId, token }); ``` `users.me` rejects with 401 once a token is invalid. Signing out never stops work the user already started. You don't need `users.me` before each request: Fin checks the session on every one. Keep the session's `expiresAt` from Create a session, and create a new session once it passes. When a request answers 401, ask `users.me`: a 401 there too means the session ended or was revoked, so create a new one; otherwise the refusal was about that request. ## Send a message ```ts import { RENDERED_CARDS } from "@nearai/financial-agents-react/model"; const conversation = await user.conversations.main(); const run = await user.runs.start( { conversationId: conversation.id, text: "What's my agent wallet worth?", context: { timeZone: "America/New_York", renders: [...RENDERED_CARDS] }, }, { idempotencyKey: messageKey }, ); ``` - **`idempotencyKey`**: make it when the user sends the message. After a lost response or unavailable admission, retry the same body with that key to follow the original run. - **`context.renders`**: the facts your app draws as cards, so the reply doesn't repeat them. With `@nearai/financial-agents-react`, send `RENDERED_CARDS`. Add `placement` when you draw a read's card only where the reply places it (`[card r7k2q]` lines), or `show` when you draw it where the agent's `show_cards` call stands (see [The journal](/concepts-journal)). `context` applies to this message only. - **`context.country`**: send the uppercase two-letter country code from your server's edge geolocation with every message, never from the browser; omit it when unavailable. Tokenized-stock purchases require a country outside the United States and Canada and an operator-enabled `tokenized_stocks` flag. Once held, these assets can only be sold, never withdrawn or sent; see [Tokenized stocks](/concepts#tokenized-stocks) for the country rule when selling. - **One run at a time**: starting another answers 409 `run_active`. Wait for `run.ended`, or call `runs.cancel`. Fin automatically retries trusted transient model failures and reviewed safe reads at most three times, under the admitted deadline and budget. A failed ending can still follow completed actions. To retry only the reply, start a follow-up in the same conversation with `profile: { tools: [] }` and an explicit request to finish the answer from retained results. Keep that follow-up's own idempotency key after a lost acknowledgement. It cannot execute tools. Use financial recovery review and fresh consent for eligible unfinished transfers, rather than resending the original action request. `model_invalid_output` identifies exhausted terminal format repair; invalid generated output still settles verified AI usage. If `runs.cancel` answers `stop_pending` or `execution_unavailable`, keep checking `runs.get` with the original run id and retry its stop as needed. A successful stop confirms the run has stopped; follow any submitted trade or funded order separately for its financial outcome. Use `conversations.create` for a separate thread, `conversations.list` to show them, and `conversations.delete` when the user removes one. A deleted conversation stays readable by id but refuses new messages with `410 conversation_deleted`, and one with a run working or an approval waiting answers `409 run_active` until it is stopped. Deleting the main conversation gives the user a new, empty one: call `conversations.main()` again rather than keeping its id. ## Relay a conversation to your browser The browser never holds the API key or the session, so your server follows the stream and relays it. This handler serves it as server-sent events from any framework with web `Request` and `Response`: Next.js, Hono, Remix, Bun or Deno. ```ts title="app/api/fin/events/route.ts" import type { FinStreamEvent } from "@nearai/financial-agents-sdk"; export async function GET(request: Request): Promise { const { userId, token } = await sessionFor(request); // your own session lookup const conversationId = new URL(request.url).searchParams.get("conversationId") ?? ""; // A reconnecting EventSource sends the last id it saw: resume after it. const cursor = Number(request.headers.get("last-event-id") ?? 0); const events = fin.user({ userId, token }).events.stream(conversationId, { cursor, signal: request.signal, }); const encoder = new TextEncoder(); const frame = (event: FinStreamEvent) => `${event.delivery === "durable" ? `id: ${event.seq}\n` : ""}data: ${JSON.stringify(event)}\n\n`; const body = new ReadableStream({ async start(controller) { for await (const event of events) controller.enqueue(encoder.encode(frame(event))); controller.close(); }, }); return new Response(body, { headers: { "content-type": "text/event-stream", "cache-control": "no-store" }, }); } ``` - **Durable events** carry their position as `seq`. Sending it as the frame's `id` lets the browser resume exactly where it left off. - **Live text** (`agent.text_delta`) has no `seq` and is never replayed. - **The relay ends** when the browser disconnects: `request.signal` ends the stream. The [React quickstart](/react-quickstart#2-fold-the-events) folds these events in the browser. ## Read a conversation's history ```ts import { paginate } from "@nearai/financial-agents-sdk"; for await (const event of paginate((cursor) => user.events.list(conversationId, cursor ? { cursor } : {}), )) { console.log(event.seq, event.type); } ``` `paginate` works with every list, since each returns `{ data, nextCursor }`. ## Decide an approval When the agent needs the user's OK, the run pauses and an `approval.opened` event arrives. Show the user exactly what it will do (the approval card in `@nearai/financial-agents-react` does), then send the decision: ```ts await user.approvals.deny(approvalId, { reason: "Not now" }); ``` The run resumes by itself. Don't start another. ### Money needs the user's signature An approval that moves money carries `authorization`: the exact message the user's registered wallet or passkey signs. Check it on your server first, then approve with the signature and the message's `controllerId` and `expiresAt`, unchanged: ```ts import { isAuthorizationFor } from "@nearai/financial-agents-sdk"; const approval = await user.approvals.get(approvalId); const toSign = approval.authorization; if (toSign) { const me = await fin.users.me({ token }); if (!isAuthorizationFor(me, finAudience, toSign)) throw new Error("Not this user's Fin request"); // The page has the wallet sign toSign.message exactly as returned. await user.approvals.approve(approval.id, { authorization: { controllerId: toSign.controllerId, expiresAt: toSign.expiresAt, signature: { kind: "evm", signature: walletSignature }, }, }); } ``` > [!IMPORTANT] > `isAuthorizationFor` guarantees the user only ever signs a Fin authorization of their own, > never a login message or other text. `finAudience` is your Fin deployment's origin. The message expires about four and a half minutes after Fin issues it; read the approval again for a fresh one. Approving doesn't mean the action worked: follow the run, and for a trade read `wallets.listTrades` with the run's id. ## Answer the agent's questions A `question.opened` event carries a questionnaire. Send the answers the user gave, or skip the card: ```ts const question = await user.questions.get(questionId); await user.questions.answer( question.id, { kind: "answers", answers: [{ id: firstQuestionId, values: [chosenValue] }] }, { idempotencyKey: crypto.randomUUID() }, ); ``` Leave out a question the user skipped; `{ kind: "skip" }` skips the whole card. An answer is a question's `id` with the chosen option `values`, or `values: []` with the user's own `customText`. Answers never approve an action or move money. A question with `amount` asks for one amount between `amount.min` and `amount.max`; its options are presets. Send a preset as its value, and an amount the user slid or typed as `customText`: ```ts await user.questions.answer( questionId, { kind: "answers", answers: [{ id: firstQuestionId, values: [], customText: "130" }] }, { idempotencyKey: crypto.randomUUID() }, ); ``` An option with `recommended: true` is the one the agent suggests; its `description` says why. ## Send feedback on a reply When the user taps a thumb under a reply, send their feedback for that run once it has ended (`completed`, `failed` or `aborted`; a run still working or waiting answers `409 run_active`). A thumbs-down may carry one reason from a fixed list (`wrong`, `unhelpful`, `slow`, `unsafe` or `other`); there is no free text: ```ts const feedback = await user.runs.sendFeedback(run.id, { rating: "down", reason: "wrong" }); // { rating: "down", reason: "wrong", createdAt, updatedAt } ``` Sending again replaces the earlier feedback, which is how the user changes it, and a retry is safe. To show a thread's thumbs, read its runs with `runs.list({ conversationId })`: each run carries `feedback`, `null` until there is any, so a reloaded page can show the thumb the user chose. When they tap it again to delete it, call `runs.deleteFeedback(run.id)`. ## Let a user talk instead of type The page records with `MediaRecorder` while `voice.get()` says `available`. A browser that cannot record a type `voice.get()` lists converts its recording to WAV first: NEAR AI's Whisper takes Ogg with Opus and WAV, so the WebM Chrome, Edge and Safari record, and older Safari's MP4, become WAV. The page posts the recording to your server as the request's body, typed as it is sent. Your server holds it to that format's size and passes it on: ```ts title="app/api/fin/voice/route.ts" const json = (body: unknown, status = 200) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }); export async function POST(request: Request): Promise { const me = fin.user(await sessionFor(request)); // your own session lookup const voice = await me.voice.get(); const contentType = request.headers.get("content-type") ?? ""; const format = voice.formats.find( (entry) => entry.contentType === contentType.split(";")[0]?.trim().toLowerCase(), ); if (voice.status !== "available" || !format) return json({ error: "not a recording" }, 400); // More than a minute of its format: refuse it before reading it. if (Number(request.headers.get("content-length") ?? 0) > format.maxBytes) return json({ error: "recording too long" }, 413); const bytes = new Uint8Array(await request.arrayBuffer()); if (bytes.byteLength > format.maxBytes) return json({ error: "recording too long" }, 413); const { text } = await me.voice.transcribe({ contentType, bytes }); return json({ text }); } ``` In the page, a recording becomes WAV with Web Audio: the browser decodes its own recording, resampled to 16 kHz as it decodes, and the channels are mixed into one. ```ts title="app/voice/wav.ts" export async function toWav(recording: Blob): Promise { const audio = await new OfflineAudioContext(1, 1, 16_000).decodeAudioData( await recording.arrayBuffer(), ); const frames = audio.length; const view = new DataView(new ArrayBuffer(44 + frames * 2)); const text = (at: number, value: string) => { for (let index = 0; index < value.length; index++) view.setUint8(at + index, value.charCodeAt(index)); }; text(0, "RIFF"); view.setUint32(4, 36 + frames * 2, true); text(8, "WAVEfmt "); view.setUint32(16, 16, true); view.setUint16(20, 1, true); // PCM view.setUint16(22, 1, true); // one channel view.setUint32(24, audio.sampleRate, true); view.setUint32(28, audio.sampleRate * 2, true); view.setUint16(32, 2, true); view.setUint16(34, 16, true); text(36, "data"); view.setUint32(40, frames * 2, true); const channels = Array.from({ length: audio.numberOfChannels }, (_, index) => audio.getChannelData(index), ); for (let frame = 0; frame < frames; frame++) { let sum = 0; for (const channel of channels) sum += channel[frame] ?? 0; const sample = Math.max(-1, Math.min(1, sum / channels.length)); view.setInt16(44 + frame * 2, sample < 0 ? sample * 0x8000 : sample * 0x7fff, true); } return new Blob([view.buffer], { type: "audio/wav" }); } ``` - **Nothing reaches the agent**: put `text` where the user writes, at their cursor, for them to read and send with `runs.start` (or `runs.steer` while the agent works). An empty `text` means no speech was heard. - **Each call is charged**: `transcribe` waits at least 75 seconds, longer than Fin waits for its speech model, and is never retried. A `503 provider_unavailable` is worth one retry of the same recording. - **`voice.get()`** changes only when an operator turns voice on or off for the user: read it once for the page, as it decides whether to show a microphone at all. ## Create the agent wallet A user has no agent wallet until they sign its creation. `wallets.get` returns the wallet, or the message that creates it: ```ts const status = await user.wallets.get(); if (status.wallet === null && status.creation) { // The page has the wallet sign status.creation.message exactly as returned. await user.wallets.create({ authorization: { controllerId: status.creation.controllerId, expiresAt: status.creation.expiresAt, signature: { kind: "evm", signature: walletSignature }, }, }); } const { assets } = await user.wallets.balances(); ``` Check the message with `isAuthorizationFor` first, as for an approval. ## Fund the agent wallet Read what the wallet accepts with `wallets.supportedAssets`. While the user picks an amount, `wallets.quoteDeposit` says what it would credit now and the least it will; it creates nothing: ```ts const { rail, network, assetId, amountRaw, maxValueLossBps } = depositTerms; const quote = await user.wallets.quoteDeposit({ rail, network, assetId, amountRaw, maxValueLossBps, }); // What the agent wallet would be credited now, and the least it will within the loss limit. console.log(quote.expectedCreditRaw, quote.minimumCreditRaw); ``` Then create the deposit with its exact terms, with the quote's `minimumCreditRaw` as theirs: ```ts const deposit = await user.wallets.createDeposit({ terms: depositTerms }, { idempotencyKey }); // deposit.instruction says where and what to send, once the address is issued. const latest = await user.wallets.getDeposit(deposit.id); console.log(latest.state); // "awaiting_deposit", "processing", then "credited" or "refunded" ``` After a timeout, find the deposit with `wallets.listDeposits({ requestKey: idempotencyKey })` instead of creating another. [Deposits, withdrawals and trades](/wallet-transfers) lists every state. When a deposit limit applies, `wallets.balances` says how much more the user can deposit, and a deposit worth more is refused with `deposit_limit_exceeded` and not recorded: ```ts import { FinApiError } from "@nearai/financial-agents-sdk"; const { depositLimit } = await user.wallets.balances(); if (depositLimit) console.log(`Up to ${depositLimit.availableCents} US cents more`); try { await user.wallets.createDeposit({ terms: depositTerms }, { idempotencyKey }); } catch (error) { if (!(error instanceof FinApiError) || error.reason !== "deposit_limit_exceeded") throw error; // Nothing was recorded: read the balances again and offer an amount within the room left. } ``` ## Withdraw from the agent wallet Quote first. Show the quote's `terms`, have the user sign its `authorization`, then withdraw with the quote's `requestKey` as the idempotency key: ```ts const quote = await user.wallets.quoteWithdrawal(withdrawalRequest); // The page shows quote.terms, and the wallet signs quote.authorization.message. const withdrawal = await user.wallets.withdraw( { terms: quote.terms, authorization: { controllerId: quote.authorization.controllerId, expiresAt: quote.authorization.expiresAt, signature: { kind: "evm", signature: walletSignature }, }, }, { idempotencyKey: quote.requestKey }, ); ``` > [!WARNING] > If the request times out, read `wallets.listWithdrawals({ requestKey: quote.requestKey })` > before anything else: the withdrawal may already be on its way. Keep the original key and body for any retry, and follow the returned withdrawal by id. If preparation was interrupted, Fin can later report a terminal refusal when it confirms nothing was sent. Signature expiry alone does not establish that: a pending or uncertain withdrawal still needs its original outcome before the user considers another payment. ## Swap in the agent wallet A swap the user makes from your own screen, with no agent run, follows the same three steps: quote, sign, send with the quote's `requestKey`. Show the quote's `terms`, including the least the swap receives, then follow the swap until its `status` is final: ```ts const quote = await user.wallets.quoteSwap(swapRequest); // The page shows quote.terms, and the wallet signs quote.authorization.message. let swap = await user.wallets.swap( { terms: quote.terms, authorization: { controllerId: quote.authorization.controllerId, expiresAt: quote.authorization.expiresAt, signature: { kind: "evm", signature: walletSignature }, }, }, { idempotencyKey: quote.requestKey }, ); while (["pending", "processing", "uncertain"].includes(swap.status)) { await new Promise((resolve) => setTimeout(resolve, 2_000)); swap = await user.wallets.getSwap(swap.id); } ``` > [!WARNING] > If the request times out, read `wallets.listSwaps({ requestKey: quote.requestKey })` before > anything else: the swap may already have run. Keep the original key and body for any retry. Follow the same swap until its outcome is known; an expired signature does not turn an uncertain swap into a safe replacement. Interrupted preparation can later close with a terminal refusal only when Fin confirms no swap was sent. To swap a tokenized stock, send the user's country, resolved by your server, with both calls: `{ ...swapRequest, context: { country } }` for the quote, and `context: { country }` beside `terms` for the swap. It applies to that one request; see [Tokenized stocks](/concepts#tokenized-stocks). ## Place a limit order in the agent wallet A limit order the user places from your own screen follows the same three steps: prepare, sign, place with the prepared `requestKey`. Show the prepared `terms`, including `minimumReceivedRaw`, the least the whole order receives, then read the order it answers: ```ts const prepared = await user.wallets.prepareOrder(orderRequest); // The page shows prepared.terms, and the wallet signs prepared.authorization.message. const order = await user.wallets.placeOrder( { terms: prepared.terms, authorization: { controllerId: prepared.authorization.controllerId, expiresAt: prepared.authorization.expiresAt, signature: { kind: "evm", signature: walletSignature }, }, }, { idempotencyKey: prepared.requestKey }, ); if (order.state === "abandoned") console.log(`Not placed: ${order.failureReason}`); ``` > [!WARNING] > If the request times out, read `wallets.listOrders({ requestKey: prepared.requestKey })` before > anything else: the order may already rest with the provider. Keep the original key and body for any retry. Interrupted preparation may later become `abandoned` when Fin confirms nothing was placed. An expired signature or an `unconfirmed` result alone is not permission to place a replacement. Use `wallets.cancelOrder(order.id)` to request a stop of that original order. A recorded `cancelRequestedAt` survives temporary outages, and Fin continues the cancellation request. After a timeout or `provider_unavailable`, read `wallets.getOrder(order.id)`; repeating the stop for that same order is safe. Confirm its final fill status and payout reconciliation before showing a cancellation or refund as complete: a fill can still win the race. A tokenized stock order takes the user's country with both calls, as a swap does. ## Find a Solana token A person types a ticker, and a ticker does not name one Solana token: many share it. Search, and when the answer is `ambiguous` let them choose by mint, which is what a buy or a sale pins. Show each candidate's risk, and treat a token whose `tradable` is false as one to read, never to buy: ```ts const found = await user.solana.searchTokens({ query: "wif" }); const buyable = found.items.filter((token) => token.tradable); if (found.ambiguous || buyable.length !== 1) { // The page lists found.items, each with its mint shortened and its risk, and the person chooses. for (const token of found.items) console.log(token.symbol, token.mint, token.risk.level, token.tradable); } else { const token = await user.solana.getToken(buyable[0].mint); console.log(`${token.symbol} ${token.priceUsd ?? "no price"} (${token.risk.level})`); } ``` `risk.level` is never a statement that a token is safe. Buying and selling are the agent's, with the user's approval in chat: see [Solana tokens](/solana-tokens) and [Approve Solana trades and transfers](/wallet-transfers#approve-solana-trades-and-transfers). ## Manage automations The agent creates automations in conversation, with the user's approval. Your app lists them and lets the user pause, resume or delete one: ```ts import { paginate } from "@nearai/financial-agents-sdk"; for await (const automation of paginate((cursor) => user.automations.list(cursor ? { cursor } : {}))) console.log(automation.name, automation.enabled); await user.automations.pause(automationId); await user.automations.resume(automationId); // The owner let the run fin paused over go: it counts toward the run limit. await user.automations.resume(automationId, { countMissedRun: true }); await user.automations.delete(automationId); ``` `automations.listRuns` reads what each firing did. See [Automations](/automations). ## Manage grids The agent creates a grid in conversation, with the user's signed approval. Your app lists the user's grids, shows each one's cells and profit, and lets the user pause, resume or cancel one: ```ts import { FinApiError, paginate } from "@nearai/financial-agents-sdk"; for await (const grid of paginate((cursor) => user.wallets.listGrids(cursor ? { cursor } : {}))) console.log(grid.state, grid.cycles, grid.realizedProfit.decimal); await user.wallets.pauseGrid(gridId); try { await user.wallets.resumeGrid(gridId); } catch (error) { if (error instanceof FinApiError && error.reason === "grid_trading_disabled") console.log("Grid trading is off for this user; the grid stays paused."); else throw error; } await user.wallets.cancelGrid(gridId); // answers "stopping"; the grid then ends "stopped" ``` A grid's orders are ordinary limit orders: `wallets.listOrders` answers them with `grid: { gridId, cell }`. See [grid trading](/wallet-transfers#grid-trading). ## Show suggestions on a page Read a page's suggestions whenever it comes into view, with what your server knows about the user right now; a read answers at once and never waits on the model: ```ts const context = { timeZone: "Europe/London", country: "GB", perpsAllowed: "false" } as const; const page = await user.suggestions.list({ surface: "orders", ...context }); if (page.status === "ready") for (const suggestion of page.suggestions) console.log(suggestion.title, suggestion.reason); // thinking: read again in a few seconds. failed and not retryable: the user's AI budget or the // hourly limit stopped Fin, so offer no Try again. if (page.status === "failed" && !page.retryable) console.log("Fin can't look right now."); const [first] = page.suggestions; if (first) { // The user opened it: check it again for fresh terms (409 suggestion_changed when it changed). const checked = await user.suggestions.review(first.id, context); console.log(checked.review.kind); // Or they picked Not now. await user.suggestions.dismiss(first.id); } ``` Each review kind is made through the routes that make it, such as Swap tokens or Place an order. See [Suggestions](/suggestions). ## Ping users' devices Read the feed from one place on your server, every few seconds, and keep the cursor it answers: ```ts import type { PartnerNotification } from "@nearai/financial-agents-sdk"; // Your own storage and delivery: where the cursor lives, and how a device is pinged. declare function savedCursor(): Promise; declare function saveCursor(cursor: string): Promise; declare function pingDevices(notification: PartnerNotification): Promise; // After an outage, an answered or lapsed approval, or anything a day old, is not worth a ping. const stale = (notification: PartnerNotification) => notification.status === "expired" || notification.status === "done" || Date.now() - Date.parse(notification.createdAt) > 86_400_000; let after = await savedCursor(); for (;;) { const page = await fin.partner.notifications(after === undefined ? {} : { after }); for (const notification of page.data) if (notification.push && !stale(notification)) await pingDevices(notification); after = page.nextCursor; // even from an empty page await saveCursor(after); if (page.data.length === 0) await new Promise((resolve) => setTimeout(resolve, 3000)); } ``` The user's own inbox reads with their session: `user.notifications.list()` for a page and its `unreadCount`, and `user.notifications.markRead({ through })` once they have seen it. See [Notifications](/notifications). ## Handle errors Every refusal rejects with a `FinApiError`: the HTTP `status`, Fin's `reason`, whether a repeat can succeed, and the `requestId` to quote. ```ts import { FinApiError } from "@nearai/financial-agents-sdk"; try { await user.runs.start({ conversationId, text: "Hello" }, { idempotencyKey: messageKey }); } catch (error) { if (!(error instanceof FinApiError)) throw error; if (error.reason === "credential_expired") { // Vouch for the user again, then repeat with the same idempotency key. } else if (error.reason === "run_active") { // Wait for run.ended, or cancel the running run. } else { console.error(`Fin refused (${error.status} ${error.reason}), request ${error.requestId}`); } } ``` | Behaviour | What the client does | | --- | --- | | Retries | Repeats a safe request (a read, a `PUT` that replaces what is there, or a write with an idempotency key) after a network failure, 429, 502, 503 or 504, up to `maxRetries` times, honouring `Retry-After`, unless Fin marked the refusal `retryable: false`. Never another write without a key. | | Timeouts | `timeoutMs` (30 seconds by default) bounds the wait for each response's headers. Every method takes `{ signal }` to abandon it. | | Your own retries | `requestRetryDelay(failures, retryAfter)` returns the same capped backoff. | | The stream | Reconnects by itself. Rejects with `FinApiError` when Fin refuses, and `FinStreamError` for a frame no reconnect can fix. Passes events it cannot read to `onUnreadable`. | [Errors](/errors) lists every reason and what to do about it. ## Watch usage and limits ```ts const usage = await fin.partner.usage(); // requests and AI spend across your users const quotas = await fin.partner.quotas(); // the limits your key runs under const budget = await user.budgets.get(); // how much of this user's AI budget is left ``` See [Usage and limits](/usage-and-quotas). ## Test without a server Pass your own `fetch` to answer requests in tests: ```ts title="approvals.test.ts" import { createFinClient } from "@nearai/financial-agents-sdk"; const fake = createFinClient({ baseUrl: "https://api.example.test", apiKey: "fin_test", fetch: async () => new Response(JSON.stringify({ data: [], nextCursor: null }), { headers: { "content-type": "application/json" }, }), }); const page = await fake.user({ userId: "customer-123", token: "t" }).approvals.list(); console.log(page.data.length); // 0 ``` ## Review a safe unfinished branch After a partial trade closes and every submitted action has a conclusive result, offer a user choice to review an unfinished branch with verified recovery evidence. The server returns the complete new request and a run for fresh approval: ```ts const trade = await user.wallets.getTrade("00000000-0000-4000-8000-000000000001"); const reviewKey = crypto.randomUUID(); // Keep this with the user's review intent for safe retries. const proposal = await user.wallets.prepareRemainingTrade(trade.id, { idempotencyKey: reviewKey }); const reviewRun = await user.runs.get(proposal.run.id); // Follow this run in the original conversation and render its pending approval normally. console.log(reviewRun.pendingApprovals); ``` Repeat the same key and body after a lost response; they return the original proposal and run. A different body under the key is refused. Choose a new key for a new review after a group closes conclusively, including a partially completed group or a verified failed prior attempt. Show and sign every new approval. Without a key, matching active or claimed selections retain the older replay behavior. When the user explicitly chooses a different all-in limit for a selected price-blocked action: ```ts const originalTradeId = "00000000-0000-4000-8000-000000000001"; const revised = await user.wallets.prepareRemainingTrade(originalTradeId, { idempotencyKey: crypto.randomUUID() }, { originalIndices: [1], maxValueLossBps: "650", // 6.5%, explicitly chosen by the user; never an automatic default. }); console.log(revised.request); // Display every returned action and limit before its new signature. ``` The maximum is 1000 basis points. The new proposal cannot lower an independently requested payout minimum. Exact-output swap reviews keep their output target and can require more input at current prices. Ordered and graph selections include unfinished prerequisites and descendants; inspect `originalIndices` and show the full returned request. Settled or uncertain actions are never sent again. Always address the original root trade and its original action positions; recovery children cannot become new sources. Never repeat the original tool request. A later receipt can resolve a result that originally remained uncertain. Read current eligibility without creating another proposal: ```ts const originalTradeId = "00000000-0000-4000-8000-000000000001"; const status = await user.wallets.getRemainingTradeActions(originalTradeId); console.log(status.candidates); // Verified local positions and unclaimed/refunded/not_executed kind. ``` A failed claimed attempt requires conclusive proof; an uncertain one is never replaced merely because it timed out. Every new attempt keeps prior receipts and requires a new owner signature. --- # SDK reference Every export of `@nearai/financial-agents-sdk`. Each method calls one API operation and shares its name: `users.create` calls [Create a user](/api-reference/users/create), whose page lists every field. Request and response types come from the same schemas the API validates with. ## Client ### `createFinClient(options)` Creates the client your server shares. It keeps no state between calls. ```ts title="fin.ts" import { createFinClient } from "@nearai/financial-agents-sdk"; export const fin = createFinClient({ baseUrl: "https://api.example.test", apiKey: "fin_example", timeoutMs: 30_000, maxRetries: 2, }); ``` | Option | Type | Description | | --- | --- | --- | | `apiKey` | `string` | Your API key (`fin_…`). Sent to `baseUrl` and nowhere else. | | `baseUrl` | `string \| URL` | Fin's API origin. A path prefix is kept. | | `fetch` | `typeof fetch` | The `fetch` to use. Defaults to the global one. | | `timeoutMs` | `number` | How long one attempt waits for response headers. Default 30 seconds. | | `maxRetries` | `number` | Retries of a safe request after a network failure, 429, 502, 503 or 504. Default 2. | A request is safe to retry when it is a `GET`, a `PUT` (it replaces what is there, so repeating it changes nothing) or carries an idempotency key. The client is a `FinClient`: the partner operations below, plus `fin.user`. ### `fin.user(credentials)` `fin.user({ userId, token })` scopes calls to one signed-in user, with `token` from `users.createSession`. It returns a `FinUserClient` with the user operations below. It costs nothing to create; make one per request. ### Call options Every method takes an options object last. | Option | Type | Description | | --- | --- | --- | | `signal` | `AbortSignal` | Abandons the request, and any retry it is waiting on. | | `idempotencyKey` | `string` | A UUID made once per intent: a repeat returns the first result. Required by `wallets.withdraw`, `wallets.swap`, `wallets.placeOrder`, `wallets.createDeposit`, `wallets.createDepositAddress`, `perps.openAccount`, `prediction.openAccount`, `solana.openAccount`, `solana.placeTrade` and `questions.answer`; optional for `runs.start`, `runs.steer` and `conversations.create`. | | `endUser` | `EndUser` | The person using your app on whose behalf the call is made, as your server saw them. Fin records it beside the request so that a security question about their account can be answered later, and uses it for nothing else. Send what your server observed, never a value your client supplied. | Their types are `CallOptions`, `IdempotentCallOptions` (key required) and `OptionallyIdempotentCallOptions` (key optional). `EndUser` is `{ ip?: string; userAgent?: string }`, and either part may be left out. Fin ignores an `ip` that is not an IPv4 or IPv6 address and keeps the first 512 characters of `userAgent`. The client sends `userAgent` as printable ASCII, dropping other characters, and leaves out an `ip` a header cannot carry, so `endUser` never fails a call. ## Users and sessions Your API key alone calls these, on `fin`. | Method | Returns | Description | | --- | --- | --- | | [`users.create(body)`](/api-reference/users/create) | `ProvisionedUser` | Creates the user for your `userId`, with their agent. A repeat returns the same user. | | [`users.createSession(userId, body)`](/api-reference/users/create-session) | `CreatedSession` | Opens a session: `{ controller }` vouches for your own sign-in, and with `createWallet` a passkey you just created opens the account (`createsWallet`); `{ challengeId, signature }` completes wallet sign-in. | | [`users.sessionChallenge(userId, body)`](/api-reference/users/session-challenge) | `SessionChallenge` | Starts wallet sign-in: the message the user signs. With `createWallet`, it also creates a new user's wallet. | | [`users.me({ token })`](/api-reference/users/me) | `User` | Who a session belongs to. Rejects with 401 once it is invalid. | | [`users.revokeSession(session)`](/api-reference/users/revoke-session) | `void` | Signs `{ userId, sessionId, token }` out. | ## Partner | Method | Returns | Description | | --- | --- | --- | | [`partner.usage(query?)`](/api-reference/partner/usage) | `PartnerUsage` | Requests and AI spend across your users. | | [`partner.quotas()`](/api-reference/partner/quotas) | `PartnerQuotas` | Shared limits and current usage; `periods[].capCents` includes audited adjustments to current caps. | | [`partner.notifications(query?)`](/api-reference/partner/notifications) | `PartnerNotificationsPage` | Your users' notifications after your cursor, oldest first, each with `push`: what your server delivers to their devices. Keep `nextCursor`, even from an empty page, and pass it back as `after`. | | [`partner.features()`](/api-reference/partner/features) | `PartnerFeatures` | Every feature an operator turns on or off for your key rather than per user, such as `market_briefs`, and whether your key has it now. Read it each time you need the answer. | ## Market briefs | Method | Returns | Description | | --- | --- | --- | | [`market.subjects.list(query?)`](/api-reference/market/subjects-list) | `MarketSubjects` | What a brief can be about, by kind or by an identifier that names it. | | [`market.briefs.create(body, { idempotencyKey })`](/api-reference/market/briefs-create) | `MarketBriefJob` | Use `mode: "news"` for news research even when quiet; default `auto` may answer `ready` at once, otherwise `generating`. | | [`market.briefs.get(id)`](/api-reference/market/briefs-get) | `MarketBriefJob` | A brief your key created: `generating`, then `ready` or `failed`. | ## Market news Your API key alone calls these too; the news is the same for every user, and no feature turns it on. | Method | Returns | Description | | --- | --- | --- | | [`market.stories.list(query?)`](/api-reference/market/stories-list) | `MarketStories` | The stories the market is telling, most recently confirmed first. Pass `evidence: "reported"` to leave out stories one unreviewed source tells, and `subject` for one coin or stock. A page can be short while `nextCursor` is set. | | [`market.stories.get(storyId)`](/api-reference/market/stories-get) | `MarketStoryDetail` | One story: every source, the figures it states as they read now, and the moves on what it is about. Rejects with 404 `story_not_found` once Fin no longer shows it. | | [`market.headlines.list(query?)`](/api-reference/market/headlines-list) | `MarketHeadlines` | Articles from reviewed publishers, newest first, with the coins and stocks each headline names. `subject` reads the newest 300. | | [`market.moves.list(query?)`](/api-reference/market/moves-list) | `MarketMoves` | What moved, newest first, one plain sentence each: one line per market and kind (per leaderboard for a lead change), a newer move replacing an older one. Narrow it with `kind` or `subject`. A page can be short while `nextCursor` is set. | | [`market.flows.get()`](/api-reference/market/flows-get) | `MarketFlows` | Market cap, alt volume, perps open interest, stablecoin supply, DEX and launchpad volume, each with its change over a day, a week and a month. | ## Conversations Everything from here on is on `fin.user({ userId, token })`. | Method | Returns | Description | | --- | --- | --- | | [`conversations.main()`](/api-reference/conversations/main) | `Conversation` | The main conversation every user starts with. | | [`conversations.create(body?, options?)`](/api-reference/conversations/create) | `Conversation` | A new conversation, for a separate thread. | | [`conversations.list(query?)`](/api-reference/conversations/list) | `ConversationPage` | The user's conversations, a page at a time. | | [`conversations.get(id)`](/api-reference/conversations/get) | `Conversation` | One conversation. | | [`conversations.delete(id)`](/api-reference/conversations/delete) | `void` | Takes it out of the list; its history stays readable, and it takes no new messages. | ## Runs A run is the agent working on one message. | Method | Returns | Description | | --- | --- | --- | | [`runs.start(body, options?)`](/api-reference/runs/start) | `Run` | Sends a message: `{ conversationId, text, profile?, context? }`. After a lost response or unavailable admission, retry with the same idempotency key and body to follow the original run. | | [`runs.get(runId)`](/api-reference/runs/get) | `Run` | One run, with its reply once completed, the automation that started it (`origin`) and what it read (`reads`). | | [`runs.list(query?)`](/api-reference/runs/list) | `RunPage` | Runs, optionally one conversation's. | | [`runs.cancel(runId)`](/api-reference/runs/cancel) | `Run` | Stops a run; resolves once it has stopped. On `stop_pending` or `execution_unavailable`, read the same run and retry its stop as needed. Stop does not confirm a payment outcome or cancel a funded order. | | [`runs.steer(runId, body, options?)`](/api-reference/runs/steer) | `Run` | Sends the user's new message to a run that is still working: `{ text }`. The agent reads it at its next step; the run lists it in `steers`. A run that ended answers `409 run_not_active`, so send the text with `runs.start` instead. | | [`runs.sendFeedback(runId, body)`](/api-reference/runs/send-feedback) | `RunFeedback` | The user's thumbs-up or thumbs-down on a reply once the run has ended: `{ rating: "up" }`, or `{ rating: "down", reason? }` with a `reason` from a fixed list. Sending again replaces it, and a run still going answers `409 run_active`; the run's `feedback` shows it. | | [`runs.deleteFeedback(runId)`](/api-reference/runs/delete-feedback) | `void` | Deletes the feedback, so the run's `feedback` is `null` again. Safe to repeat. | `StartRunInput.context.perpsAllowed` is an optional boolean your server reports for the current user's perpetual-futures region availability. Unlike `context.contacts`, it participates in retry identity; a changed value under the same key conflicts. Replaying an unchanged request does not refresh its saved observation time. See [perps availability](/concepts#perps-availability). ## Voice Let the user say their message instead of typing it. See [talking instead of typing](/concepts#talking-instead-of-typing). | Method | Returns | Description | | --- | --- | --- | | [`voice.get()`](/api-reference/voice/get) | `Voice` | Whether the user can talk instead of type now (`status`), the longest recording to send (`maxSeconds`), and the `formats` it may be, each with its largest size (`maxBytes`). Show a microphone only while `status` is `available`. | | [`voice.transcribe(recording)`](/api-reference/voice/transcribe) | `Transcription` | One recording, `{ contentType, bytes }`, in a type `voice.get()` lists (a `Blob` from `MediaRecorder` as it is when its type is listed, else made WAV first, as the SDK recipes guide shows), answered as `{ text }` to put where the user writes. Nothing reaches the agent until they send it; an empty `text` means no speech was heard. It waits at least 75 seconds whatever the client's `timeoutMs` (Fin waits up to a minute for its speech model), and is never retried by the client, since each call is charged. | ## Events | Method | Returns | Description | | --- | --- | --- | | [`events.stream(conversationId, options?)`](/api-reference/events/stream) | `AsyncIterableIterator` | The conversation's events: a replay, then live. | | [`events.list(conversationId, query?)`](/api-reference/events/list) | `EventPage` | Durable events after a cursor, oldest first. `prediction.withdrawal` updates its original call, including after the run ends; its unique linked deposit receipt establishes arrival. | `events.stream` replays from `cursor`, then follows live. It reconnects after a dropped connection, a close, or a 429, 502, 503 or 504, resuming after the last durable event and honouring `Retry-After`. It ends when `signal` aborts. | Option | Type | Description | | --- | --- | --- | | `cursor` | `number` | Resume after this durable `seq`. Default 0, the whole conversation. | | `signal` | `AbortSignal` | Ends the stream. | | `endUser` | `EndUser` | The person the stream is opened for, as a call's `endUser`. Every connection names them, a reconnect included. | | `reconnect` | `boolean` | Reconnect when the stream drops. Default true. | | `onUnreadable` | `(event: UnreadableEvent) => void` | Receives each event this version cannot read, which the stream skips. | Each `FinStreamEvent` is `{ type, delivery: "durable", seq, requestId, payload }` or `{ type, delivery: "live", payload }`, and narrows on `type`. Live text arrives as `agent.text_delta` until the durable `agent.entry` replaces it. [Events](/events) lists every type. ## Approvals and questions | Method | Returns | Description | | --- | --- | --- | | [`approvals.list(query?)`](/api-reference/approvals/list) | `ApprovalPage` | Approvals, including exact one-shot `prediction_withdraw` consent; pending ones by default, `status: "all"` for every one, and `conversationId` for one chat's. An approved money action names the wallet that signed it in `signedBy`. | | [`approvals.get(approvalId)`](/api-reference/approvals/get) | `Approval` | Exactly what it would do, and for money the `authorization` to sign. A Polymarket withdrawal binds the exact pUSD `amountRaw` and explicit `maxLossBps`. | | [`approvals.approve(approvalId, body)`](/api-reference/approvals/approve) | `Approval` | Approves the stored terms. Money, including Polymarket withdrawal, carries `{ authorization: { controllerId, expiresAt, signature } }`. | | [`approvals.deny(approvalId, body)`](/api-reference/approvals/deny) | `Approval` | Denies, with an optional `reason`, and returns the approval. Denying withdrawal consent does not submit a transfer. | | [`questions.get(questionId)`](/api-reference/questions/get) | `Question` | A questionnaire the agent asked. | | [`questions.answer(questionId, body, options)`](/api-reference/questions/answer) | `Question` | Answers `{ kind: "answers", answers }`, leaving out any skipped question, or skips `{ kind: "skip" }`. | ## Portfolio | Method | Returns | Description | | --- | --- | --- | | [`portfolio.get()`](/api-reference/portfolio/get) | `Portfolio` | What the agent owns across every account now: the total, each account and each holding, with `provisional` figures and the unpriced holdings left out in `excluded`. Use it for any figure you show; it also asks Fin to re-read accounts last read over two minutes ago. See [the portfolio and its history](/wallet-transfers#portfolio-and-its-history). | | [`portfolio.history(query)`](/api-reference/portfolio/history) | `PortfolioHistory` | The value over a `range` (default `1D`), optionally at a coarser `step`, with each point's gain and `marks`, and the range's `summary`. Its last point is `portfolio.get()`'s total. | ## Agent wallet | Method | Returns | Description | | --- | --- | --- | | [`wallets.get()`](/api-reference/wallets/get) | `WalletStatus` | The wallet, or while there is none, the `creation` message to sign. | | [`wallets.create(body)`](/api-reference/wallets/create) | `Wallet` | Creates the wallet with the user's signature, with an account-opening sign-in's (`signIn`), or with nothing from the session that opened the account with a new passkey. | | [`wallets.confirm(body)`](/api-reference/wallets/confirm) | `Wallet` | Confirms ownership of an existing wallet. Moves no funds. | | [`wallets.startSetup(body)`](/api-reference/wallets/start-setup) | `WalletSetup` | Sets up the wallet with the same signature as `wallets.create`: the first Agent API step the user signs where Agent API wallets apply to them, otherwise the wallet at once. | | [`wallets.continueSetup(body)`](/api-reference/wallets/continue-setup) | `WalletSetup` | Sends the user's signature of a setup step: the next step, or the wallet. | | [`wallets.renewAccess(body)`](/api-reference/wallets/renew-access) | `WalletSetup` | Renews the agent's access to an Agent API wallet: the step the user signs next. | | [`wallets.addDestination(body)`](/api-reference/wallets/add-destination) | `WalletSetup` | Lets an Agent API wallet pay one more address (withdrawals, sends, venue funding): the step the user signs (then `wallets.continueSetup`), or the wallet when it is already allowed. `policy_change_throttled` with `Retry-After` within a few minutes of the last change. | | [`wallets.getAccount()`](/api-reference/wallets/get-account) | `AccountWalletStatus` | The wallet whatever its kind, named by `intentsAccount` (`near`, or an Agent API wallet's `evm`), or while there is none, the `creation` message to sign; `renewal` for an Agent API wallet. Use it once your partner is enabled for Agent API wallets. | | [`wallets.getAccountBalances()`](/api-reference/wallets/get-account-balances) | `AccountWalletBalances` | `wallets.balances` with the wallet named by `intentsAccount`, for any wallet. | | [`wallets.openAccountSession()`](/api-reference/wallets/open-account-session) | `AccountWalletSession` | `wallets.createSession` naming the account by `intentsAccount`, for any wallet. Keep it on your server. | | [`wallets.balances()`](/api-reference/wallets/balances) | `WalletBalances` | Available wallet holdings and a `portfolio` summary: the account's total, with what is available, in open orders and on its way from orders. Preserve a null total as unknown; `reasons` says why. See [current portfolio values](/wallet-transfers#see-what-the-wallet-can-hold). | | [`wallets.supportedAssets()`](/api-reference/wallets/supported-assets) | `SupportedAssets` | What the wallet can hold, receive and send. | | [`wallets.listEarnVaults()`](/api-reference/wallets/list-earn-vaults) | `EarnVaults` | The curated yield vaults, each provider's current, variable rate (`null` when it could not be read), the vault's `payment` asset and the user's own `position`: what their trades paid and returned in that asset, `null` with no shares. | | [`wallets.createSession()`](/api-reference/wallets/create-session) | `WalletSession` | A 1Click session for reading the wallet. Keep it on your server. | ### Deposits and withdrawals | Method | Returns | Description | | --- | --- | --- | | [`wallets.quoteDeposit(body)`](/api-reference/wallets/quote-deposit) | `DepositQuote` | What a deposit of an exact amount would credit now, and the least it will. Creates nothing. | | [`wallets.createDeposit(body, options)`](/api-reference/wallets/create-deposit) | `Deposit` | Where and what to send to fund the wallet with an exact amount. | | [`wallets.getDeposit(depositId)`](/api-reference/wallets/get-deposit) | `Deposit` | One deposit and where it stands. | | [`wallets.listDeposits(query?)`](/api-reference/wallets/list-deposits) | `DepositPage` | Newest first; `requestKey` finds one after a timeout. | | [`wallets.createDepositAddress(body, options)`](/api-reference/wallets/create-deposit-address) | `DepositAddress` | A one-time address for one transfer of any amount, when the amount isn't known yet. | | [`wallets.getDepositAddress(depositAddressId)`](/api-reference/wallets/get-deposit-address) | `DepositAddress` | One deposit address and how its transfer is going. | | [`wallets.reportDepositTransaction(depositAddressId, body)`](/api-reference/wallets/report-deposit-transaction) | `DepositAddress` | Names the transfer that paid an address, so it is found sooner. | | [`wallets.quoteWithdrawal(body)`](/api-reference/wallets/quote-withdrawal) | `WithdrawalQuote` | The priced terms and the message the user signs. | | [`wallets.withdraw(body, options)`](/api-reference/wallets/withdraw) | `Withdrawal` | Withdraws with the quote's `terms` and signature; the key is its `requestKey`. After response loss, look up that key and follow the original withdrawal. Any retry keeps the same key and body; expiry alone never resolves uncertainty. | | [`wallets.getWithdrawal(withdrawalId)`](/api-reference/wallets/get-withdrawal) | `Withdrawal` | One withdrawal and where it stands. | | [`wallets.listWithdrawals(query?)`](/api-reference/wallets/list-withdrawals) | `WithdrawalPage` | Newest first; `requestKey` finds one after a timeout. | ### Swaps | Method | Returns | Description | | --- | --- | --- | | [`wallets.quoteSwap(body)`](/api-reference/wallets/quote-swap) | `SwapQuote` | The priced terms, with the least the swap receives, and the message the user signs. | | [`wallets.swap(body, options)`](/api-reference/wallets/swap) | `Swap` | Swaps with the quote's `terms` and signature; the key is its `requestKey`. After response loss, look up that key and follow the original swap. Any retry keeps the same key and body; expiry alone never permits a replacement. | | [`wallets.getSwap(swapId)`](/api-reference/wallets/get-swap) | `Swap` | One swap and where it stands. | | [`wallets.listSwaps(query?)`](/api-reference/wallets/list-swaps) | `SwapPage` | The user's own swaps, newest first; `requestKey` finds one after a timeout. | ### Trades and orders | Method | Returns | Description | | --- | --- | --- | | [`wallets.listTrades(query?)`](/api-reference/wallets/list-trades) | `WalletTradePage` | The agent's trades, newest first; `runId` narrows to one run. | | [`wallets.getTrade(tradeId)`](/api-reference/wallets/get-trade) | `WalletTrade` | One trade with its legs and settlement. | | [`wallets.getRemainingTradeActions(tradeId, options?)`](/api-reference/wallets/get-remaining-trade-actions) | `RemainingTradeActions` | Read current verified recovery candidates after later terminal receipts. This does not create a proposal or execute anything. Candidates distinguish unclaimed, conclusively not-executed and finally refunded prior attempts. | | [`wallets.prepareRemainingTrade(tradeId, options?, body?)`](/api-reference/wallets/prepare-remaining-trade) | `RemainingTradeProposal` | A fresh review of the original root trade's verified recoverable unfinished branches. `options.idempotencyKey` identifies this review intent: reuse it with the same body after a lost response. Optional `body.originalIndices` selects original positions; `body.maxValueLossBps` explicitly chooses a higher all-in limit up to 1000 bps. The returned request needs a new owner signature. A conclusively closed group permits a new keyed review of remaining actions. | | [`wallets.prepareOrder(body)`](/api-reference/wallets/prepare-order) | `PreparedOrder` | The order's terms, with the least it receives in all, and the message the user signs. | | [`wallets.placeOrder(body, options)`](/api-reference/wallets/place-order) | `WalletOrder` | Places it with the prepared `terms` and signature; the key is its `requestKey`. After response loss, look up that key and follow the original order. Any retry keeps the same key and body; an unconfirmed order must not be replaced merely because its signature expired. | | [`wallets.listOrders(query?)`](/api-reference/wallets/list-orders) | `WalletOrderPage` | Limit orders, newest first; `requestKey` finds one after a timeout. | | [`wallets.getOrder(orderId)`](/api-reference/wallets/get-order) | `WalletOrder` | One limit order, including reported position and separate payout reconciliation. | | [`wallets.cancelOrder(orderId)`](/api-reference/wallets/cancel-order) | `WalletOrder` | Records a cancellation request that continues after temporary outages; safe to repeat for the same order. Read the original order to confirm cancellation or a raced fill, and `position` for payout reconciliation. A request is not a confirmed refund. | ### Grids The agent creates a grid in chat, with the user's signed approval; these read and control it. See [grid trading](/wallet-transfers#grid-trading). | Method | Returns | Description | | --- | --- | --- | | [`wallets.listGrids(query?)`](/api-reference/wallets/list-grids) | `GridPage` | The user's grids, newest first. | | [`wallets.getGrid(gridId)`](/api-reference/wallets/get-grid) | `Grid` | One grid: its approved `terms`, each cell's live order, completed `cycles`, `realizedProfit` and `heldBaseRaw`. | | [`wallets.pauseGrid(gridId)`](/api-reference/wallets/pause-grid) | `Grid` | Pauses an `active` grid: its resting orders are cancelled and nothing is placed. `409 grid_not_active` in any other state that has not ended. | | [`wallets.resumeGrid(gridId)`](/api-reference/wallets/resume-grid) | `Grid` | Resumes a `paused` grid under the grant the user approved: every cell places again. `409 grid_not_paused` in any other state that has not ended; `403 grid_trading_disabled` when grid trading is off for the user. | | [`wallets.cancelGrid(gridId)`](/api-reference/wallets/cancel-grid) | `Grid` | Stops an `active` or `paused` grid for good: the grant is revoked and its orders cancelled; nothing is sold, and what it bought stays in the wallet. Never gated, and safe to repeat. | A grid that ended answers `410 grid_ended` to every control, except that cancelling a grid the user already cancelled returns it. ## Perps account | Method | Returns | Description | | --- | --- | --- | | [`perps.openAccount(options)`](/api-reference/perps/open-account) | `PerpsAccount` | Opens the account with a required idempotency key. Needs an agent wallet and the `perps` feature enabled; moves no funds. The agent's first deposit or opening order opens it too. | | [`perps.getAccount()`](/api-reference/perps/get-account) | `PerpsAccount` | The opened account and its live Hyperliquid state with its open positions, even when the `perps` feature is off; 404 until opened. | `PerpsAccount` is `{ address, createdAt, state }`. Its `PerpsAccountState` is either `{ status: "observed", observedAt, accountValueUsd, withdrawableUsd, marginUsedUsd, positionCount, positions }` or `{ status: "unavailable", reason }`. All three USD values are exact decimal strings; an unavailable state is not a zero balance. Each `PerpsPosition` is `{ coin, size, entryPriceUsd, positionValueUsd, unrealizedPnlUsd, marginUsedUsd, liquidationPriceUsd, leverage, marginMode }`, largest first and at most 100; its PnL is already in `accountValueUsd`, so never add it again. See [opening a perps account](/wallet-transfers#open-a-perps-account). Positions may also include `fundingSinceOpenUsd`, the whole position's exact USD funding paid since open (negative when received), already reflected in the account value. ## Prediction-market account and orders | Method | Returns | Description | | --- | --- | --- | | [`prediction.openAccount(options)`](/api-reference/prediction/open-account) | `PredictionAccount` | Opens the Polymarket account with a required idempotency key; Fin continues setup automatically. Reuse the key after a lost response. Needs an agent wallet and the `prediction` feature enabled; moves no funds. The agent's first funding or order starts it too. | | [`prediction.getAccount()`](/api-reference/prediction/get-account) | `PredictionAccount` | Poll while `opening` until `ready`; reads never submit setup. Returns the account, its live pUSD balance and its positions even when the feature is off; 404 until opened. | | [`prediction.prepareOrder(order)`](/api-reference/prediction/prepare-order) | `PreparedPredictionOrder` | Checks a Polymarket order the user places themselves and returns it with the `authorization` message they sign and the `requestKey` to place it under. Nothing is reserved or placed. | | [`prediction.placeOrder(body, { idempotencyKey })`](/api-reference/prediction/place-order) | `PredictionOrder` | Places the prepared order with the user's signature, with `requestKey` as the idempotency key. A retry with the same key and body answers the same order; an order the worker refuses is `409 prediction_order_changed`. | | [`prediction.listOrders(query?)`](/api-reference/prediction/list-orders) | `PredictionOrderPage` | Own retained orders in stable id order: `{ cursor?, limit? }`. Follow `nextCursor`; reads remain available when placement is disabled. | | [`prediction.getOrder(orderId)`](/api-reference/prediction/get-order) | `PredictionOrder` | One order and its latest match/settlement observations. Use the resource's Fin `id`, not its `venueOrderId`; absent or foreign orders return 404. | | [`prediction.cancelOrder(orderId)`](/api-reference/prediction/cancel-order) | `PredictionOrder` | Requests same-order cancellation without a new spending approval. Safe to repeat; an uncertain result is not proof of cancellation. Existing fills remain visible. | `PredictionAccount` is `{ address, signer, status, createdAt, balance, positions }`. Its `PredictionAccountBalance` is `{ status: "observed", observedAt, pusd }` or `{ status: "unavailable", reason }`; `pusd` is an exact decimal string and an unavailable balance is not zero. `PredictionAccountPositions` is `{ status: "observed", observedAt, stale, positions, truncated }` or `{ status: "unavailable", reason }`; each `PredictionPosition` is `{ assetId, marketQuestion, outcome, sizeSharesDecimal, averagePriceUsdDecimal, currentPriceUsdDecimal, currentValueUsdDecimal, costUsdDecimal, unrealizedPnlUsdDecimal, redeemable }`, largest value first and at most 100. `stale` is true while Polymarket rate-limits Fin and `positions` is the last read within the past hour, as of `observedAt`: show them as last known and never size a sale from them. See [opening a prediction-market account](/wallet-transfers#open-a-prediction-market-account). ## Solana account and tokens All thirteen are on `fin.user({ userId, token })`. The token reads take no `userId` in their path but need the user's session as every user operation does. | Method | Returns | Description | | --- | --- | --- | | [`solana.openAccount(options)`](/api-reference/solana/open-account) | `SolanaAccount` | Opens the agent's own Solana account with a required idempotency key. Needs an agent wallet and the `solana` feature enabled; moves no funds. The agent's first approved buy or funding opens it too; returns SOL and recognized token balances. | | [`solana.getAccount()`](/api-reference/solana/get-account) | `SolanaAccount` | The opened account's SOL and recognized token balances, even when the feature is off; unresolved recognition makes holdings unavailable. 404 `no_account` until opened. | | [`solana.searchTokens({ query })`](/api-reference/solana/search-tokens) | `SolanaTokenSearch` | Candidates for a ticker, a name or a pasted mint, best match first, each with Fin's risk verdict. `ambiguous` says several share the top symbol. Needs the `solana` feature. | | [`solana.listTokens(query?)`](/api-reference/solana/list-tokens) | `SolanaTokenList` | Sampled discovery (`trending`, `traded`, `organic`, `new`, `gainers`) with membership, exact-value liquidity/capitalization filters, age/launchpad filters, sorting and frozen `nextCursor` pagination. Includes classification, ranking reasons, source coverage and evidence gaps. Needs the `solana` feature. | | [`solana.getToken(mint)`](/api-reference/solana/get-token) | `SolanaTokenDetail` | One token by its mint: market data, activity and the risk verdict. Needs no feature. | | [`solana.getTokenChart(mint, query?)`](/api-reference/solana/get-token-chart) | `SolanaTokenChart` | Closing prices and actual history coverage from the token's deepest pool, or why there are none: `{ interval?: "1m" \| "5m" \| "15m" \| "1h" \| "4h" \| "1d" }`. Needs no feature. | | [`solana.getTokenHolders(mint)`](/api-reference/solana/get-token-holders) | `SolanaTokenHolders` | The ten largest holders from the chain, each owner once with its share of the supply, `kind` (`wallet` or `program`, such as a pool or a bonding curve), the `venue` of a pool Fin recognizes and `creator`, with the holder count's `holderChange` as a percent per window; or `unavailable` with its reason. Needs no feature. | | [`solana.listTokenSparklines(query)`](/api-reference/solana/list-token-sparklines) | `SolanaTokenSparklines` | A small price line for each of up to 25 tokens from the prices Fin sampled, or why it has none: `{ mint, interval?: "1h" \| "6h" \| "24h" }`. Needs the `solana` feature. | | [`solana.listTokenLaunchStatus(query)`](/api-reference/solana/list-token-launch-status) | `SolanaTokenLaunchStatus` | Where each of up to 25 tokens stands on its launchpad: `curve` with `progressPct`, `graduated` with `graduatedAt`, or `unknown`: `{ mint }`. Needs the `solana` feature. | | [`solana.getTokenIcon(mint)`](/api-reference/solana/get-token-icon) | `SolanaTokenIcon` | The token's icon as Fin serves it: `{ contentType, bytes }`, a PNG, JPEG, WebP or GIF. A 404 `FinApiError` when there is no usable icon, and a `FinApiError` with the answer's status when it is none of those types. Needs no feature. | | [`solana.prepareTrade(body)`](/api-reference/solana/prepare-trade) | `PreparedSolanaTrade` | Checks a buy or a sale the user places themselves, as the agent's own are checked, and returns the exact `trade` to show, `authorization.message` for the user to sign and the `requestKey`. Nothing is reserved or moved. A buy needs the `solana` feature; a sale needs the opened account (404 `no_account`). A token Fin does not trade is 403 `solana_token_not_tradable`. A buy carrying `payWith` is refused: only a chat approval pays a funding with a coin. | | [`solana.placeTrade(body, options)`](/api-reference/solana/place-trade) | `SolanaTrade` | Starts the prepared trade with `{ trade, authorization }` and `idempotencyKey: prepared.requestKey`, from the agent's own Solana account; a first buy opens the account. Answers `201` with status `processing`. One trade runs at a time per user: a second is 409 `solana_trade_changed`, as is a token whose decimals or program changed. Retry the same key and body after a timeout; you get the same trade. | | [`solana.getTrade(tradeId)`](/api-reference/solana/get-trade) | `SolanaTrade` | A trade the user placed: `status`, `failureReason`, the `stage` it is on while it runs, `paid`, `received` and every transaction it signed. Its status is final by its `completeBy`, at most nine minutes past the signature. `activity.list` lists these trades as `solana_trade` items. | `SolanaAccount` is `{ address, createdAt, holdings }`. Its `SolanaHoldings` is either `{ status: "observed", observedAt, sol, tokens, valueUsd, unpricedCount }` or `{ status: "unavailable", reason }`. Every amount is exact: `lamports` and each token's `amountRaw` are integer strings in the asset's smallest unit, and USD values are decimal strings. `tokens` includes canonical wrapped SOL, venue-verified tokens without a suspicious flag whose mint facts match the chain, and tokens this account has a confirmed landed buy of, including buys paid in SOL. Names, symbols and prices alone do not establish recognition. Unrecognized receipts contribute to neither `valueUsd` nor `unpricedCount`. A recognized token without a price stays listed and counts in `unpricedCount`; unavailable balances or unresolved recognition are not an empty account. See [opening a Solana account](/wallet-transfers#open-a-solana-account), [finding Solana tokens](/solana-tokens) and [trading one from your own screen](/solana-tokens#trade-a-token-from-your-own-screen). `PredictionOrder` is `{ id, order, observation }`; the venue hash is `observation.venueOrderId`. Raw share, collateral and fee fields use six decimals. `PredictionOrderPage` is `{ data, nextCursor }`. The agent places through the exact signed chat approval; the user places their own with `prediction.prepareOrder` and `prediction.placeOrder`. See [Polymarket orders](/wallet-transfers#approve-polymarket-orders) for consent and recovery, and [placing one yourself](/wallet-transfers#place-a-polymarket-order-yourself). ## Activity and budget | Method | Returns | Description | | --- | --- | --- | | [`activity.list(query?)`](/api-reference/activity/list) | `ActivityPage` | Trades, swaps, withdrawals, deposits, deposit addresses, Solana trades and transfers (a sale of several coins under one approval is its own `solana_sell_many` item), and automation changes, newest first. | | [`budgets.get()`](/api-reference/budgets/get) | `Budget` | How much of the user's AI budget is left. | ## Features | Method | Returns | Description | | --- | --- | --- | | [`users.listFeatures()`](/api-reference/users/list-features) | `UserFeatures` | Every feature an operator turns on or off per user, such as `perps` or `solana`, and whether this user has it now. Show only what they can use, and read it again when they come back. | | Feature | Default | Consumer behavior | | --- | --- | --- | | `feed_extension` | off | Experimental feed extension pages and post handoff. Read it for the signed-in user; do not show `/ticket`, `/ticket/done` or `/chat/from-post` until it is explicitly enabled. Missing or failed reads mean off. It gates no financial tools or exits and grants no permission to transact. | A post handoff is a draft, not a run. Only the user's explicit Send starts a new conversation; the post is quoted JSON data in the ordinary run text, not a new request field. The host freezes the user's feature decision at admission and adds its quoted-post guidance only to enabled requests, preserving the same statement when history is restored after targeting changes. Features decided for your key rather than per user, such as `market_briefs`, are on [`partner.features()`](#partner), which your key calls alone. ## Notifications | Method | Returns | Description | | --- | --- | --- | | [`notifications.list(query?)`](/api-reference/notifications/list) | `NotificationsPage` | What Fin told the user, newest first, with each one's text ready to show and `unreadCount` for a badge: `{ unread?, conversationId?, cursor?, limit? }`. | | [`notifications.markRead(body)`](/api-reference/notifications/mark-read) | `MarkedNotificationsRead` | Marks `{ notificationIds }`, or `{ through }` the newest one the user saw and everything older, read on every device. Safe to repeat. | See [notifications](/notifications) for the inbox, marking read and delivering pings from the feed, and for fin's own notices and the `options` they carry. ## Suggestions | Method | Returns | Description | | --- | --- | --- | | [`suggestions.list(query?)`](/api-reference/suggestions/list) | `PageSuggestions` | What Fin suggests for one page, best first, from its latest read of the whole account: `{ surface?, timeZone?, country?, perpsAllowed? }`. It never waits on the model; read again while `status` is `thinking`. | | [`suggestions.review(suggestionId, query?)`](/api-reference/suggestions/review) | `SuggestedMove` | One suggestion checked again against the account now, with fresh review terms: call it when the user opens a review. `409 suggestion_changed` when it no longer holds. | | [`suggestions.dismiss(suggestionId)`](/api-reference/suggestions/dismiss) | `void` | Not now: Fin leaves that kind of move on that subject out until the subject changes or seven days pass. | See [suggestions](/suggestions) for how Fin's suggestions for the whole account are read, reviewed and set aside. ## Idea baskets Limited to enabled partners. See [idea baskets](/idea-baskets) for valuation and shared holdings. | Method | Returns | Description | | --- | --- | --- | | [`baskets.list(query?)`](/api-reference/baskets/list) | `BasketPage` | The user's idea baskets, newest first: `{ cursor?, limit? }`. Each includes its unused venue money. | | [`baskets.get(basketId)`](/api-reference/baskets/get) | `Basket` | One basket with settlement quantities, estimated values, cash kept back, its approval time and step count, failed steps by label, unused venue money, and server-computed `performance` (a planned seven-day estimate or actual since-bought return). Percentage decimals use percent units; missing history is explicit, never zero. | | [`baskets.delete(basketId)`](/api-reference/baskets/delete) | `void` | Removes a basket from the user's ideas, draft or bought. Moves nothing. Refused with `basket_buying` while it buys and `basket_awaiting_approval` while an approval to buy it is open. Not gated by the baskets feature. | | [`baskets.link(basketId, { piece, operationId })`](/api-reference/baskets/link) | `Basket` | Links an order the user placed to a step that did not buy, from that step's `failures[].linkable`, and returns the detailed basket including refreshed `performance`. Moves nothing; a repeat of the same link answers the basket. Refused with `basket_step_not_failed`, `basket_step_linked` or `basket_order_not_linkable`. | ## Automations | Method | Returns | Description | | --- | --- | --- | | [`automations.backtest(input)`](/api-reference/automations/backtest) | `BacktestReport` | Replays a draft or saved automation with explicit starting holdings, per-purchase `contributeInputs: true`, or finite upfront `funding: "strategy_budget"`; automatic modes require empty initial holdings. Read capital contributions, status and limitations before showing performance. | | [`automations.list(query?)`](/api-reference/automations/list) | `AutomationPage` | The user's automations. | | [`automations.get(automationId)`](/api-reference/automations/get) | `Automation` | One automation. | | [`automations.pause(automationId)`](/api-reference/automations/pause) | `Automation` | Pauses it until resumed. | | [`automations.resume(automationId, { countMissedRun? })`](/api-reference/automations/resume) | `Automation` | Resumes it under the permission it already has. `countMissedRun: true` counts the run fin paused over. | | [`automations.delete(automationId)`](/api-reference/automations/delete) | `void` | Deletes it. | | [`automations.listRuns(automationId, query?)`](/api-reference/automations/list-runs) | `AutomationRunPage` | What its firings did. | | [`automations.getRun(automationId, runId)`](/api-reference/automations/get-run) | `AutomationRun` | One firing. | | [`automations.listReadings(automationId, query?)`](/api-reference/automations/list-readings) | `AutomationReadings` | What its sources read over time, field by field. | | [`automations.listSources()`](/api-reference/automations/list-sources) | `AutomationSourceCatalog` | What an automation can watch. | | [`automations.rotateWebhookSecret(automationId)`](/api-reference/automations/rotate-webhook-secret) | `WebhookSecret` | A new webhook secret, shown once. | ## Errors ### `FinApiError` Every method rejects with it when Fin answers outside 2xx, and `solana.getTokenIcon` also when the answer is not a PNG, JPEG, WebP or GIF. | Member | Type | Description | | --- | --- | --- | | `status` | `number` | The HTTP status. | | `reason` | `string \| undefined` | Fin's machine-readable reason, such as `credential_expired`. See [Errors](/errors). | | `requestId` | `string \| undefined` | What to quote when you report the failure. | | `retryable` | `boolean` | Whether repeating the same request can succeed. | | `problem` | `ProblemDetails \| null` | The RFC 9457 problem details, when the response was one. | | `response` | `Response` | The response itself. | ### `FinStreamError` `events.stream` rejects with it for a frame no reconnect can fix: an id that disagrees with its sequence, data that is not JSON, or an envelope that is not an event. ## Helpers ### `paginate(list)` Iterates every item of a list, page after page. Pass a function that reads one page: ```ts import { paginate } from "@nearai/financial-agents-sdk"; for await (const approval of paginate((cursor) => user.approvals.list(cursor ? { cursor } : {}))) console.log(approval.summary); ``` It stops after the last page, or rejects with the first page that fails. `Page` is one page: `{ data: T[]; nextCursor: string | null }`. ### `isAuthorizationFor(subject, audience, toSign)` Whether `toSign` is Fin's authorization for this user, their agent and their registered wallet. `toSign` is any message Fin issues for a signature: an approval's `authorization`, a withdrawal or swap quote's `authorization`, or wallet creation's `creation`. `subject` is the user as `users.me` returns them, and `audience` your Fin deployment's origin. > [!IMPORTANT] > Run it on your server before your page asks the user to sign, so they only ever sign a Fin > authorization of their own. ### `requestRetryDelay(failures, retryAfter?)` Milliseconds to wait before repeating a refused request: capped exponential backoff (1 s, 2 s, 4 s, up to 30 s), or longer when `Retry-After` asks. `failures` counts the attempts that failed. The client uses it for its own retries. ## Types Every request and response type is exported by name. | Area | Types | | --- | --- | | Users and partner | `CreateUserInput`, `ProvisionedUser`, `User`, `SessionChallengeInput`, `SessionChallenge`, `CreateSessionInput`, `CreatedSession`, `PartnerUsageQuery`, `PartnerUsage`, `PartnerQuotas`, `PartnerNotificationsQuery`, `PartnerNotificationsPage`, `PartnerNotification` | | Market briefs | `CreateMarketBriefInput`, `MarketBriefJob`, `MarketBrief`, `MarketBriefMode`, `MarketMetricProvenance`, `MarketSubjectsQuery`, `MarketSubjects` | | Market news | `MarketStoriesQuery`, `MarketStories`, `MarketStory`, `MarketStoryDetail`, `MarketNewsSubject`, `MarketNewsSource`, `MarketFigure`, `MarketHeadlinesQuery`, `MarketHeadlines`, `MarketHeadline`, `MarketMovesQuery`, `MarketMoves`, `MarketNewsMove`, `MarketFlows`, `MarketFlow` | | Conversations | `Conversation`, `CreateConversationInput`, `ListConversationsQuery`, `ConversationPage` | | Runs | `StartRunInput`, `Run`, `ListRunsQuery`, `RunPage`, `SteerRunInput`, `RunSteer`, `SendRunFeedbackInput`, `RunFeedback`, `RunFeedbackRating`, `RunFeedbackReason` | | Events | `FinEventType`, `EventPayload`, `FinStreamEvent`, `StreamOptions`, `UnreadableEvent`, `ListEventsQuery`, `EventPage` | | Approvals and questions | `Approval`, `ListApprovalsQuery`, `ApprovalPage`, `ApproveInput`, `DenyInput`, `Question`, `AnswerQuestionInput` | | Portfolio | `Portfolio`, `PortfolioAssetRef`, `PortfolioHistoryQuery`, `PortfolioHistory` | | Agent wallet | `WalletStatus`, `Wallet`, `CreateWalletInput`, `ConfirmWalletInput`, `WalletSession`, `WalletBalances`, `WalletPortfolioSummary`, `SupportedAssets` | | Perps | `PerpsAccount`, `PerpsAccountState` | | Solana | `SolanaAccount`, `SolanaHoldings`, `SolanaTokenHolding`, `SearchSolanaTokensQuery`, `SolanaTokenSearch`, `ListSolanaTokensQuery`, `SolanaTokenList`, `SolanaTokenSummary`, `SolanaTokenDetail`, `SolanaRisk`, `SolanaTokenChartQuery`, `SolanaTokenChart`, `PrepareSolanaTradeInput`, `PreparedSolanaTrade`, `PlaceSolanaTradeInput`, `SolanaTrade` | | Prediction markets | `PredictionAccount`, `PredictionAccountBalance`, `PredictionOrder`, `PredictionOrderPage`, `ListPredictionOrdersQuery` | | Deposits and withdrawals | `CreateDepositInput`, `Deposit`, `ListDepositsQuery`, `DepositPage`, `CreateDepositAddressInput`, `DepositAddress`, `ReportDepositTransactionInput`, `QuoteWithdrawalInput`, `WithdrawalQuote`, `WithdrawInput`, `Withdrawal`, `ListWithdrawalsQuery`, `WithdrawalPage` | | Swaps | `QuoteSwapInput`, `SwapQuote`, `SwapInput`, `Swap`, `ListSwapsQuery`, `SwapPage` | | Trades and orders | `ListTradesQuery`, `WalletTradePage`, `WalletTrade`, `PrepareOrderInput`, `PreparedOrder`, `PlaceOrderInput`, `ListOrdersQuery`, `WalletOrderPage`, `WalletOrder` | | Grids | `ListGridsQuery`, `GridPage`, `Grid` | | Activity and budget | `ActivityQuery`, `ActivityPage`, `ActivityItem`, `Budget` | | Features | `UserFeatures`, `UserFeature`, `PartnerFeatures`, `PartnerFeature` | | Notifications | `NotificationsQuery`, `NotificationsPage`, `Notification`, `NotificationOption`, `MarkNotificationsReadInput`, `MarkedNotificationsRead` | | Suggestions | `PageSuggestionsQuery`, `PageSuggestions`, `SuggestedMove`, `ReviewTerms`, `SuggestionReviewQuery` | | Automations | `Automation` (with `missedRun`), `ListAutomationsQuery`, `AutomationPage`, `AutomationRun`, `ListAutomationRunsQuery`, `AutomationRunPage`, `AutomationSourceCatalog`, `WebhookSecret` | | Idea baskets | `Basket`, `BasketPerformance`, `BasketPerformancePosition`, `BasketPerformancePoint`, `BasketSummary`, `BasketHolding`, `ListBasketsQuery`, `BasketPage`, `BasketLinkableOrder`, `BasketLinkInput` | | Signatures | `AuthorizationToSign`, `SignedAuthorization`, `AuthorizationSubject` | | Client | `FinClient`, `FinUserClient`, `FinClientOptions`, `UserCredentials`, `CallOptions`, `EndUser`, `IdempotentCallOptions`, `OptionallyIdempotentCallOptions`, `Page`, `ProblemDetails` | `FinEventType` is every event type and `EventPayload` one type's payload. `AuthorizationToSign` is a message to sign, with its `controllerId` and `expiresAt`; `SignedAuthorization` is the signature you send back with them. --- # React quickstart Draw a Fin conversation inside your own React chat. Your app keeps its bubbles, composer, layout and scrolling; `@nearai/financial-agents-react` draws what is Fin's: the agent's replies, its activity, the approval and question cards, result cards and how each run ended. The components never fetch. Your server reads Fin with [`@nearai/financial-agents-sdk`](/sdk-quickstart) and relays the events; the components draw them and report what the user did. ## Before you begin - **React 19** with `react-dom`, and `@base-ui/react` 1.3 or later. - **A relay** from your server to the page, such as the [server-sent events recipe](/sdk-recipes#relay-a-conversation-to-your-browser). - **TypeScript 5.4 or later**, if you type-check. ## 1. Install and import the styles ```sh npm install @nearai/financial-agents-react @base-ui/react ``` Import the stylesheet once, beside your global CSS: ```ts title="app/layout.tsx" import "@nearai/financial-agents-react/styles.css"; ``` It styles nothing outside Fin's blocks: its rules sit in a `fin` cascade layer, and every class and variable is prefixed. In a Tailwind app, declare the layer order above your Tailwind import: ```css title="app/globals.css" @layer theme, base, fin, components, utilities; @import "tailwindcss"; ``` ## 2. Fold the events `threadReducer` folds the events your relay sends, exactly as the SDK yields them, into the thread. It ignores an event it has already seen, so a replay after a reconnect is harmless. ```ts title="use-thread.ts" import { initialThread, type StreamEvent, threadReducer } from "@nearai/financial-agents-react/model"; import { useEffect, useReducer } from "react"; export function useThread(conversationId: string) { const [thread, dispatch] = useReducer(threadReducer, initialThread); useEffect(() => { const url = `/api/fin/events?conversationId=${encodeURIComponent(conversationId)}`; const source = new EventSource(url); source.onmessage = (message) => dispatch(JSON.parse(message.data) as StreamEvent); return () => source.close(); }, [conversationId]); return thread; } ``` Give the component that holds a thread `key={conversationId}`, so another conversation starts from `initialThread`. ## 3. Add the provider `FinUIProvider` tells Fin's blocks how your app links. It carries no data. ```tsx title="fin-chat.tsx" import { FinUIProvider } from "@nearai/financial-agents-react"; import type { ReactNode } from "react"; export function FinChat({ children }: { children: ReactNode }) { return ( `/agent/automations/${id}`, orders: () => "/agent/orders", assets: () => "/agent/wallet", }} > {children} ); } ``` | Prop | Purpose | | --- | --- | | `link` | Your router's link component, such as Next.js's `Link`. Defaults to a plain anchor. | | `routes` | The agent's pages in your app that cards link to. Unset routes keep near.com's paths. Name `asset` to link every token Fin draws to your page for it. | | `tokens` | What each token looks like. Defaults to near.com's list; see [Tokens and chains](/tokens-and-chains). | ## 4. Draw the transcript `transcriptEntries(thread)` lists what to draw, in order. Draw messages your way, the agent's text with `MessageMarkdown`, and everything else with `FinEntry`: ```tsx title="transcript.tsx" import { ApprovalExpansionProvider, type ApprovalHandlers, FinEntry, MessageMarkdown, } from "@nearai/financial-agents-react"; import { entryKey, replyContext, type ThreadState, transcriptEntries, } from "@nearai/financial-agents-react/model"; import { useMemo } from "react"; export function Transcript(props: { thread: ThreadState; approvals: ApprovalHandlers }) { const { thread, approvals } = props; // Recomputed only when the thread changes, so each reply redraws only when its text does. const context = useMemo(() => replyContext(thread.items), [thread.items]); return (
{transcriptEntries(thread).map((entry) => { const key = entryKey(entry); if (entry.kind === "item" && entry.item.kind === "user") return

{entry.item.text}

; if (entry.kind === "item" && entry.item.kind === "assistant") return ; return (
); })} {thread.streamingText ? ( ) : null}
); } ``` - **An `item` entry** is one thing in the thread: a message (`user`, `assistant`), a trade (`tool`), its receipt (`settlement`), a `question`, an `approval`, or a `run` ending. - **An `activity` entry** folds the tool calls between two parts of a reply into one line, with the cards their results draw. - **`FinEntry`** draws nothing for a message, which is yours, and may draw several blocks: give each entry the container and spacing your layout wants. - **`replyContext`** gives a reply's bolded assets their icon and trend line. - **Live text** is `thread.streamingText` until the saved reply replaces it; `streaming` draws the caret. ## 5. Handle approvals and questions The approval and question cards report the user's choice through handlers you pass `FinEntry`, and show the decision in progress while your server sends it: ```ts title="use-approvals.ts" import type { ApprovalHandlers } from "@nearai/financial-agents-react"; import { useState } from "react"; export function useApprovals(): ApprovalHandlers { const [decidingId, setDecidingId] = useState(null); const [conflicts, setConflicts] = useState>({}); return { decidingId, conflicts, onDecide: async (approvalId, approve) => { setDecidingId(approvalId); const refusal = await decide(approvalId, approve); // your server approves or denies if (refusal) setConflicts((all) => ({ ...all, [approvalId]: refusal })); setDecidingId(null); }, onDismissConflict: (approvalId) => setConflicts(({ [approvalId]: _dismissed, ...rest }) => rest), }; } ``` Your server sends the decision with `approvals.approve` or `approvals.deny`; an action that moves money also needs the user's [wallet signature](/sdk-recipes#money-needs-the-user-s-signature). `QuestionHandlers` work the same way for `questions`, answered with `questions.answer`. > [!NOTE] > The card draws the exact terms of the contract Fin derived, never the model's words. A contract > this version cannot read offers only Cancel and asks the user to update the app. ## 6. Let the user send feedback on a reply Under a finished reply `FinEntry` can draw a thumb each way; a thumbs-down also offers a short fixed list of reasons. Pass `feedback` handlers and it does; leave it out and no thumbs are drawn. The feedback the user already gave is the run's `feedback`, which your server reads for the whole thread with one `runs.list({ conversationId })`, and a tap reports the new feedback: ```ts title="use-feedback.ts" import type { FeedbackHandlers } from "@nearai/financial-agents-react"; import { useState } from "react"; export function useFeedback(initial: FeedbackHandlers["ratings"]): FeedbackHandlers { const [ratings, setRatings] = useState(initial); const [busyRunIds, setBusyRunIds] = useState([]); const [errors, setErrors] = useState>({}); return { ratings, busyRunIds, errors, onRate: async (runId, feedback) => { setBusyRunIds((ids) => [...ids, runId]); setErrors(({ [runId]: _cleared, ...rest }) => rest); const refusal = await rate(runId, feedback); // your server sends or deletes the feedback if (refusal) setErrors((all) => ({ ...all, [runId]: refusal })); else setRatings((all) => ({ ...all, [runId]: feedback })); setBusyRunIds((ids) => ids.filter((id) => id !== runId)); }, }; } ``` Pass it to each entry as ``. Your server sends feedback with `runs.sendFeedback`, and `null` (the user tapped the thumb they had chosen) with `runs.deleteFeedback`. Fin takes feedback on a run that has ended, so the thumbs appear under a finished or failed reply only, and never under one the user stopped. Several replies can be saving at once: `busyRunIds` holds each one's thumbs until its own answer lands. ## 7. Offer the next steps A reply can end with replies the agent suggests sending next. `MessageMarkdown` leaves them out; offer them under the latest reply with `NextSteps`: ```tsx title="reply.tsx" import { MessageMarkdown, NextSteps } from "@nearai/financial-agents-react"; import { type ReplyContext, splitReplyNextSteps } from "@nearai/financial-agents-react/model"; export function Reply(props: { text: string; context: ReplyContext; latest: boolean }) { const { nextSteps } = splitReplyNextSteps(props.text); return (
{props.latest ? : null}
); } ``` ## 8. Let the cards carry the facts When your server starts a run, send `RENDERED_CARDS` as `context.renders` ([recipe](/sdk-recipes#send-a-message)). The agent then leaves receipts, saved automations, the wallet, limit orders, saved contacts and grids to the cards instead of repeating them in its reply. The contacts card links to your own contacts page when you name it as `routes.contacts`. Send `context.country` from your server's edge geolocation with every message too; [Tokenized stocks](/concepts#tokenized-stocks) explains the country and purchase restrictions. ## Next steps - [**Components reference**](/react-components) — Every block, its props and its parts. - [**Theming**](/react-theming) — Make the blocks look like your product. - [**View models**](/react-model) — The logic behind the blocks, for your own markup. --- # Components reference Every block `@nearai/financial-agents-react` exports. Most apps place only `FinEntry`, `MessageMarkdown` and `NextSteps`, as the [React quickstart](/react-quickstart) does, and `FinEntry` places the rest. Place a block yourself to lay out a conversation your own way, or to show a card elsewhere. Every block takes Fin's data as props, reports what the user does through callbacks, and never fetches. > [!TIP] > Each block's root carries `data-fin-part=""` and takes `className`. A block with named > parts also takes `classNames`, and each part carries `data-fin-part="-"`. See > [Theming](/react-theming). ## Entries ### `FinEntry` Draws one transcript entry that is Fin's: an activity line and its cards, a trade, a receipt, a question, an approval with the automation it saved or the grid it started, or a run's ending. A `user` or `assistant` message is yours, so it draws nothing for one. | Prop | Type | Description | | --- | --- | --- | | `entry` | `TranscriptEntry` | The entry to draw, from `transcriptEntries(thread)`. | | `thread` | `ThreadState` | The thread the entry came from. Links a call to its approval, trade and run. | | `approvals` | `ApprovalHandlers` | What deciding an approval does. | | `questions` | `QuestionHandlers` | What answering a question does. Without it, questions can't be answered. | | `automations` | `Record` | Automations as they are now, by id, for saved automations' cards. `automationIdsOf(thread.items)` names them. | | `grids` | `GridHandlers` | What a grid card's Pause, Resume and Stop do, and grids as they are now, by id. Without it a grid's card draws the snapshot its tool returned, with no controls. | | `feedback` | `FeedbackHandlers` | What a thumb on a reply does. Without it, no thumbs are drawn under a reply. | | `questionVariant` | `QuestionCardVariant` | How a question's choices are drawn, as `QuestionCard`'s `variant` takes it. `list` unless you pass `cards`. | | `loadPriceHistory` | `PriceHistoryLoader` | Loads another range for a `PriceCard`'s range tabs from your own market data. Without it a price card draws only the window the agent read. | | `resultCards` | `OptInResultCard[]` | The result cards to draw beyond the ones every chat draws: `market` for a `market_history` read (`PriceCard` or `ComparisonCard`), `vaults` for an `earn_vaults` read (`VaultsCard`), `predictions` for the prediction-market reads (`PredictionsCard`, `PredictionMarketCard`, `PredictionPreviewCard`, `PredictionOrdersCard`), `solana` for the four Solana reads (`TokenCandidatesCard`, `MemecoinsCard`, `SolanaTokenCard`, `SolanaHoldingsCard`). None by default, so a chat that upgrades draws what it drew before: those reads show only their activity line. | | `walletVariant` | `"list" \| "holdings"` | How a balance read is drawn: `list` (the default) draws `WalletCard`, `holdings` draws `HoldingsCard`. | | `predictionVariant` | `"default" \| "visual"` | How Polymarket cards are drawn. `default` keeps the existing funding/order rendering and shows withdrawal's exact consent rows and risk. `visual` draws a `prediction_fund` approval as a Pays → Holds hero with its risk facts above the buttons and its progress as stages (sending, at the bridge, bridge reports completed, a bridge failure's recovery, the endings where nothing moved); `prediction_withdraw` as exact pUSD Pays → estimated USDC Holds, with its estimate-only loss limit, own Polygon route and always-visible risk notice; a `prediction_order_place` approval as a Pays → Holds hero (the most it pays, the shares it holds, the payout, the implied chance and the order's lifetime) with its risk facts above the buttons, its open, settling, cancelled and unconfirmed states as a matched meter with rows, a filled order as a receipt, and declined, expired or unreviewable approvals as stopped stages; `PredictionOrdersCard` as rows with a status badge; and the research cards as outcome bars, a yes/no split and a fill meter. | | `onDraft` | `(message) => void` | Puts a message in your composer for the user to edit and send: a vault deposit, Polymarket order cancellation, a visual order card's Check again, or next order page. Without it, these draft buttons are not shown. | | `onSend` | `(message, card: { runId }) => void` | Sends a message as the user's next one, as your composer would: a `TokenCandidatesCard`'s Use this one, an open `MemecoinsCard` row's Buy…, or the next move a partly done Solana buy or sale offers (`SolanaReceipt`). Each names its token by mint and moves nothing: the agent goes on, and anything that moves money waits for its approval. `card.runId` is the run that drew the card (`null` when the thread can't tell). Steer the message into that run only while that same run waits on a question: the run skips the question, and nothing answers it. Never answer a question with it. Otherwise send it, or queue it behind a run that works or waits on an approval, which a steer would decline. Without it, no such buttons. | | `sendDisabled` | `boolean` | Holds the buttons that call `onSend`. Pass `true` from a click until the message reaches `thread` (the run it starts, or its steer), so a double click sends once, and while you can't take another message, such as when your queue is full. They hold while a run works as well. | | `loadSolanaToken` | `SolanaTokenLoader` | Reads a token for a `MemecoinsCard` row the user opens: `chart({ mint, interval, signal })` answers Get a Solana token's chart, `token({ mint, signal })` (optional) Get a Solana token, for its holders. Without it an open row shows the figures the list read carried, its warnings and its actions. | | `runSummary` | `boolean` | Draws `RunProgress` above the first approval of a run that proposed moving money while it works and, at its ending, its finished steps and a `RunReceipt` when two or more swaps settled. Off by default. | | `approvalAside` | `(approval: ApprovalView) => ReactNode` | Your own content inside a pending approval's card, between its terms and its buttons (the card's `aside`), such as how the proposal would have done on past prices. Return `null` for none. None by default, so the card draws as it always has. | | `automationTerms` | `"disclosure" \| "summary"` | `disclosure` (default) retains an automation approval's Review terms and Exact terms controls. `summary` keeps its canonical headline, trade rows, limits, exit notes and decisions while omitting both controls, the terms grid and mobile terms sheet. A Solana standing grant always retains Exact terms with its full signed definition. Stored input, authorization and signing are unchanged. Other approval types are unchanged. | | `requestText` | `(text: string) => string` | Turns a run's first user message into the request its `RunProgress` and `RunReceipt` name, so framing your app added to that message, such as page context, stays out of the card's title. The message as sent by default. | | `className` | `string` | Classes for the block it draws. | | Entry | Draws | | --- | --- | | `activity` | `ActivityGroup`, then a card per result that draws one: `AutomationCard`, `WalletCard` (or `HoldingsCard`), `OrdersCard`, `ContactsCard`, `GridCard` (one per grid an `intents_grids` read returned, compact when there are several); with `resultCards`, a `PriceCard` (one asset) or `ComparisonCard` (several) for `market_history`, `VaultsCard` for `earn_vaults`, `PredictionsCard`, `PredictionMarketCard` and `PredictionPreviewCard` for `prediction_markets`, `prediction_market` and `prediction_preview`, and `TokenCandidatesCard`, `MemecoinsCard`, `SolanaTokenCard` and `SolanaHoldingsCard` for `solana_token_search`, `memecoins_top`, `solana_token` and `solana_account` | | `item` of kind `tool` | `ToolCallCard`: a trade, through to its settlement | | `item` of kind `settlement` | `SettlementReceipt` | | `item` of kind `question` | `QuestionCard` | | `item` of kind `approval` | With `runSummary`, `RunProgress` above a run's first approval while it works; then `ApprovalCard`, then the `AutomationCard` of the automation it saved, the `SolanaReceipt` of a Solana call whose outcome recorded what it did, or the `GridCard` of the grid `grid_create`, `grid_pause`, `grid_resume` or `grid_cancel` returned | | `item` of kind `run` | With `runSummary`, a money run's `RunProgress` and, with two swaps settled or more, its `RunReceipt`; then `RunFooter`, with the user's thumbs under the reply when `feedback` is passed | | `item` of kind `user` or `assistant` | Nothing: your messages | `AutomationCard` also draws an `automations_archive` receipt: Archived, future work disabled, retained history, and honest pending/confirmed remote contract revocation. It warns that future exits stop without selling a position or undoing submitted transactions. An archive receipt outranks stale pre-archive automation props. Archiving opens no approval, so the receipt is the only card it draws. The same `automations` map refreshes management detail after reload; no additional route or SDK method is needed. `ApprovalHandlers` are `{ decidingId, conflicts, onDecide, onDismissConflict, onProposeAgain?, onReviewRemaining?, remainingReviewStates?, remainingReviewErrors?, holdings?, vaultRates?, predictionBalance? }`: | Field | Type | Description | | --- | --- | --- | | `decidingId` | `string \| null` | The approval being decided now; its card shows the decision in progress. | | `conflicts` | `Record` | Fin's refusals by approval id, until dismissed. | | `onDecide` | `(approvalId, approve) => void` | The user approved (`true`) or denied (`false`). Call `approvals.approve` or `approvals.deny`. | | `onDismissConflict` | `(approvalId) => void` | The user dismissed a refusal. | | `onProposeAgain` | `(approval) => void` | The user pressed an expired card's Propose again. Send the agent a message asking for it again, such as one naming `approvalContent(approval).headline`; it proposes afresh at current prices. Without it the expired card offers no button. | | `onReviewRemaining` | `(operationId, options?) => void` | Prepare a fresh review of proven unclaimed actions. `options` may select `originalIndices` and an explicit higher `maxValueLossBps`; pass it as the third argument to `wallets.prepareRemainingTrade(operationId, {}, options)`. The server rechecks claims and ownership before creating new signed terms. | | `remainingReviewStates` | `Record` | Review status by operation id, disabling the button while pending or accepted. | | `remainingReviewErrors` | `Record` | Review refusals by operation id. | | `holdings` | `PricedHolding[]` | The agent wallet's priced holdings, to value a contract's terms today. | | `vaultRates` | `VaultRate[]` | The curated vaults' current rates (`{ assetId, rate }`, an entry of the Earn vaults route's `vaults`), so a deposit into a vault states its yield. | | `predictionBalance` | `{ pusd, readAt } \| null` | The live pUSD balance of the agent's own Polymarket deposit wallet, from Get the Polymarket account's observed `balance` (`pusd`, and `observedAt` as `readAt`). With `predictionVariant="visual"`, a funding whose bridge reports completed leads with it when it was read after that report, as the wallet's balance and never as this funding's credit. | `QuestionHandlers` are `{ busyQuestionId, errors, onAnswer, onDismissError }`: | Field | Type | Description | | --- | --- | --- | | `busyQuestionId` | `string \| null` | The question being answered now. | | `errors` | `Record` | Fin's refusals by question id, until dismissed. | | `onAnswer` | `(questionId, answer) => void` | The user answered or skipped. Call `questions.answer` with it. | | `onDismissError` | `(questionId) => void` | The user dismissed a refusal. | `GridHandlers` are `{ current?, busy?, onPause?, onResume?, onCancel? }`. A control is drawn only when you pass its handler: | Field | Type | Description | | --- | --- | --- | | `current` | `Record` | Grids as they are now, by id: a card draws whichever of this and its tool's snapshot is newer (`updatedAt`). `gridIdsOf(thread.items)` names them; refetch with `wallets.getGrid`. | | `busy` | `{ gridId, action } \| null` | The control being sent now (`action` is a `GridAction`: `pause`, `resume` or `cancel`); its button waits and the card's others hold. | | `onPause` | `(gridId) => void` | The user pressed Pause on a running grid. Call `wallets.pauseGrid`. | | `onResume` | `(gridId) => void` | The user pressed Resume on a paused grid. Call `wallets.resumeGrid`. | | `onCancel` | `(gridId) => void` | The user pressed Stop. Confirm first if your app asks, then call `wallets.cancelGrid`. | `FeedbackHandlers` are `{ ratings, busyRunIds, errors, onRate, tooltip? }`: | Field | Type | Description | | --- | --- | --- | | `ratings` | `Record` | The user's feedback on each run by id, as Fin returned it (the run's `feedback`). A run that is missing or `null` has none. | | `busyRunIds` | `readonly string[]` | The runs whose feedback is being saved now; each one's thumbs hold until it lands, and the others stay free. | | `errors` | `Record` | Fin's refusals by run id, in words, shown beside that run's thumbs until the next tap. | | `onRate` | `(runId, feedback) => void` | The user sent, changed or deleted feedback. Call `runs.sendFeedback` with it, or `runs.deleteFeedback` when `feedback` is `null`. | | `tooltip` | `ControlTooltip` | Wraps each icon-only control under a reply (the thumbs, the reasons' Skip) in your own tooltip. Without it they draw as they always have. | Build `holdings` from the wallet's balances. Fin names held assets by opaque `assetId`s and contracts name tokens by id, so map each through `catalogTokenId`: ```ts import { catalogTokenId, type PricedHolding } from "@nearai/financial-agents-react/model"; const holdings = balances.assets.flatMap((asset): PricedHolding[] => { const tokenId = catalogTokenId(asset.assetId); return tokenId ? [{ tokenId, decimals: asset.decimals, amountRaw: asset.amountRaw, priceUsdDecimal: asset.priceUsdDecimal }] : []; }); ``` ## Replies ### `MessageMarkdown` The agent's reply in your product's prose, drawn richer where its text says so: signed changes coloured (`+4.2%` green, `-1.3%` red), tables as panels with figures aligned, linked sources as chips with the provider's logo, and bolded assets with their icon and trend line. With `routes.asset` set, a ticker in the reply links to your page for the token: only one spelled exactly as the thread or the token list spells it (`NEAR`, never "near the price"), and never inside code or a link. It leaves out the suggested next steps, which you offer with `NextSteps`, the share lines Fin writes for an app that shares answers (`splitReplyNextSteps(text).shareLines`), and any line that places a card (`[card r7k2q]`), which you draw where `threadTurns` puts it. | Prop | Type | Description | | --- | --- | --- | | `text` | `string` | The reply as Fin wrote it, next steps included. | | `streaming` | `boolean` | Live text: draws the caret after the last line. | | `size` | `"sm" \| "md"` | `md` (the default) in a conversation, `sm` in a narrow panel. | | `context` | `ReplyContext` | What the thread knows about the assets a reply names: `replyContext(thread.items)`. | | `className` | `string` | Classes for the prose. | | `classNames` | `{ code?, table?, link?, word?, asset?, assetIcon? }` | Classes for its code blocks, tables and source links; drawn as words, each word, a bolded asset and its icon. | | `words` | `boolean` | Draws the reply as words, for an app that shows them arriving: while it streams, each word is its own part with the spaces left between them and live text carries no caret; a change keeps its direction as `data-change`, and a bolded asset is its own part with its icon before its name. A finished reply keeps its text whole. Off by default. | Parts: `message-markdown-code`, `message-markdown-table`, `message-markdown-link`, and with `words`, `message-markdown-word`, `message-markdown-asset` and `message-markdown-asset-icon`. ### `NextSteps` The replies the agent suggests sending next, each a button that sends it as the user's message. Offer them under the latest reply only. A step only sends text: anything it leads to still meets its approval card. | Prop | Type | Description | | --- | --- | --- | | `steps` | `readonly string[]` | `splitReplyNextSteps(text).nextSteps`. Draws nothing for none. | | `onPick` | `(step: string) => void` | Send the step as the user's message. | | `disabled` | `boolean` | Holds the buttons while a message is sending or a run is going. | | `className` | `string` | Classes for the root. | ## Agent activity ### `ActivityGroup` The tool calls between two parts of a reply, as one quiet line: what the agent is doing now, or what it checked, with the providers' logos. Opened, it lists each step with its provider and read time, down to the exact input and result. | Prop | Type | Description | | --- | --- | --- | | `steps` | `readonly ActivityStep[]` | The calls, each from `activityStep(item, runEndedAfter(thread, item))`. | | `className` | `string` | Classes for the root. | ### `ToolCallCard` A trade the agent ran, followed to the journal's proof of its ending: the exact input and result, provider references once completed, and Fin's reason otherwise. An automation's tool row can offer the same failed-action recovery as an approval card. `FinEntry` forwards the review handler, original-operation mapping and review state to both. The server-prepared review opens a normal run for a fresh owner signature; it grants no additional authority to the automation. | Prop | Type | Description | | --- | --- | --- | | `item` | `ToolItem` | The tool call, as the thread holds it. | | `execution` | `ExecutionView` | The execution it drove, if any: `executionForTool(thread, item)`. | | `ended` | `boolean` | The run ended after this call without an outcome. | | `onReviewRemaining` | `(options?) => void` | Prepare a fresh review of proven unclaimed Intents actions. `options` contains `originalIndices?` and an explicitly chosen `maxValueLossBps?`. Pending or uncertain submissions expose no recovery controls. | | `remainingReviewStatus` | `"preparing" \| "opened"` | Holds the review controls while the request is pending or accepted. | | `remainingReviewError` | `string` | A visible refusal from preparing the review. | | `className` | `string` | Classes for the row. | | `classNames` | `{ details?, swaps?, recovery? }` | Classes for the opened details, execution rows and failed-action recovery panel. | Parts: `tool-call-card-details`, `tool-call-card-swaps`, `tool-call-card-recovery`. ## Approvals and questions ### `ApprovalCard` Shows the exact action before anything moves, then shrinks in place and follows it to the journal's proof of its ending. A money action reads as the terms of the contract Fin derived, never the model's words. The stored input, contract, result and receipts stay word for word behind a disclosure. For `automations_edit`, the frozen stored action renders the exact target snapshot, current definition, requested patch and complete result visibly before deciding. Prior spent/used/reserved and resulting remaining allowance are shown without recomputing or renewing them in the browser. If the old or new definition has a contract, retain your existing owner-signature authorization handler; `onDecide` reports a decision, not a substitute for the signed exact request. An unreadable frozen edit can be canceled but never approved. `composite` is deliberately **Cancel-only** in this packaged card, including a valid contract: the shared block does not draw its pieces. Its approval action is guarded independently of `approvalConsent`. A missing composite grant is also refusal-only. The fin app's enabled basket feature owns its own exact piece renderer; upgrading this package does not make baskets, funded orders or cash-outs approvable in a partner's existing UI. Keep signing the server-issued authorization message; neither an approval summary nor progress events can substitute for its terms. For `prediction_withdraw`, `ApprovalCard` draws the withdrawal card from a matching one-shot `prediction_withdraw` grant and exact `{ amountRaw, maxLossBps }` input. It shows the full six-decimal pUSD debit, own-account native Polygon USDC route, explicit loss limit and expiry; malformed or mismatched terms permit refusal only. The risk notice remains visible before approval: the limit checks the bridge's estimate before transfer, not an on-chain minimum or a guaranteed final conversion or Intents credit. Bridge liquidity can hold, fail or reduce delivery. `predictionVariant="visual"` uses an exact pUSD Pays → estimated USDC Holds hero with loss-limit, quote and Polygon-route facts and a Details disclosure. Progress remains open while unresolved; terminal decisions use a one-line fold. A confirmed outgoing transfer and bridge-reported completion are not arrival. Only the unique own-account deposit's final receipt proves attributed arrival or refund, credited once by the existing deposit ledger. `prediction.withdrawal` events update the original card, including after the run ends, and outrank a late original `tool.result`; uncertainty never offers an automatic resend. Apps drawing their own cards can use `derivePredictionWithdrawView`, `PredictionWithdrawView`, `predictionWithdrawProgress`, `PredictionWithdrawProgress` and `PREDICTION_WITHDRAW_RISK` from the model exports. For `prediction_order_place`, the card shows the exact market, outcome, side, price, quantity, order type and fee/spend checks from its matching `prediction_order` grant. The risk notice remains visible before approval: price is signed, but fees are checked before submission and lifetime is enforced by the venue. Missing or mismatched grants permit refusal only. `prediction.order` observations update the original call's result. A partial match is not settlement, and cancellation does not reverse earlier fills. With `predictionVariant="visual"`, the approval's secondary button reads Decline (Cancel is reserved for cancelling an order), a sell shows what it receives at its floor rather than a zero spend limit, and a failed trade is never drawn as success. | Prop | Type | Description | | --- | --- | --- | | `approval` | `ApprovalView` | The approval: `thread.approvals[approvalId]`. | | `busy` | `boolean` | A decision is being recorded; holds the buttons. | | `onDecide` | `(approve: boolean) => void` | The user approved (`true`) or denied (`false`). | | `outcome` | `ToolItem["outcome"]` | The linked call's result: `toolForApproval(thread, approval)?.outcome`. | | `running` | `boolean` | The linked call is still running. | | `ended` | `boolean` | The run ended after the call without an outcome. | | `execution` | `ExecutionView` | The execution the approval produced. | | `predictionVariant` | `"default" \| "visual"` | Opt-in Polymarket heroes and progressive disclosure: consent remains visible while pending, secondary figures live under Details, and decided funding / observed orders start closed to their state and key figure. Defaults to the original rendering. | | `predictionBalance` | `{ pusd: string; readAt: string } \| null` | Host-read exact decimal pUSD balance of the agent's own deposit wallet. Only shown after a route-matching bridge COMPLETED report, when `readAt` is not earlier than that observation's `observedAtMs`; never attributed to this funding. | | `onDraft` | `(message: string) => void` | With `predictionVariant="visual"`, a placed Polymarket order's Cancel order (open or partly matched) and Check again (failed, rejected or unconfirmed) put a request in your composer, outside the fold; the card executes neither. Without it, those buttons are not drawn. | | `reference` | `string` | The request id to quote for a failure or a hold. | | `conflict` | `string \| null` | Fin refused the decision; shown until dismissed. | | `onDismissConflict` | `() => void` | The user dismissed the refusal. | | `holdings` | `PricedHolding[]` | The wallet's balances and prices, for estimates. | | `vaultRates` | `VaultRate[]` | The curated vaults' current rates. A deposit into one notes the provider's rate as variable, and with a scheduled harvest roughly what each period earns on the deposit at that rate. No rate, no note. | | `tokenRisks` | `ReadonlyMap` | What the chat's reads found of each Solana token's risk, by mint (`solanaRisks(thread.items)`): a Solana ticket wears its token's worst warning beside its title. `FinEntry` passes it. | | `ruleConflict` | `RuleConflict \| null` | Another rule drawing on the same asset; the card asks first. | | `expanded` | `boolean` | Terms open. Uncontrolled when absent. For visual Polymarket approvals, also initializes the status and secondary-figure Details folds open; later disclosure toggles are local. | | `automationTerms` | `"disclosure" \| "summary"` | `summary` omits a standing automation's Review terms and Exact terms controls, terms grid and mobile terms sheet, retaining its canonical summary, trade rows, limits, exit notes and decisions. A Solana standing grant always retains Exact terms with its full signed definition. Stored input, authorization and signing are unchanged. `disclosure` is the default. Other approval types keep their existing terms behavior. | | `onToggleTerms` | `(open: boolean) => void` | The terms opened or closed; pair with `expanded`. | | `decidedAt` | `string` | When a final state happened, for the status band. | | `onRetry` | `() => void` | A failed card's Try again. | | `onProposeAgain` | `() => void` | An expired card's Propose again. | | `onReviewRemaining` | `(options?) => void` | Review only selected unstarted actions, optionally with an explicitly entered higher total-loss bound. Price-limit, insufficient-funds and availability failures have separate recovery panels; no uncertain submission can enter recovery. `options` contains `originalIndices?` and `maxValueLossBps?`. | | `remainingReviewStatus` | `"preparing" \| "opened"` | Disables the review button while the request is pending or accepted. | | `remainingReviewError` | `string` | A visible refusal from preparing the review. | | `onMakeRule` | `() => void` | A settled card's Make this an automation. | | `onSendToOneFirst` | `() => void` | For a send to several addresses: send to one first. | | `now` | `number` | The clock for validity text; stories and tests pin it. | | `holdProgress` | `number` | Pins the hold-to-approve fill, for stories. | | `aside` | `ReactNode` | Your own content inside a pending trade, automation or order card, between its terms and its decision buttons. Drawn only while the card waits for a decision; it never replaces the terms, and the card's buttons stay the only way to decide. | | `className` | `string` | Classes for the card. | | `classNames` | `{ band?, body?, headline?, terms?, actions?, evidence?, hero?, figures?, rail?, footnote?, details?, trigger?, limits?, recovery? }` | Classes for its parts. | A follow-up button (`onRetry`, `onProposeAgain`, `onMakeRule`, `onSendToOneFirst`) appears only when you pass its handler. A `RuleConflict` names the other rule (`ruleName`) and, when known, what both draw on (`asset`, such as `0.175 BTC`). A limit order's card reads the order itself. One that pays with a stablecoin is a buy, priced per the asset bought (`Buy NEAR with 10 USDC at ≤ 4 USDC per NEAR`); any other is the sale it is. Once decided, the card says what happened to the order (placed, not placed and why, or unconfirmed when 1Click's answer was lost), never that it executed. Cancelling an order opens no approval; a cancel card from an older conversation still says whether the cancel was requested. A Hyperliquid order's card (`perps_order_place`) reads its one-shot `perps_order` grant and leads with a trade ticket: a side chip (`Long`, `Short`, `Close long`, or `Exits` for a take-profit, stop-loss or trailing stop on the position already held) beside the coin and its leverage with the margin mode the user chose (`3× cross`, `3× isolated`; an order approved before margin modes existed reads as cross), and the exact size large with its exact notional under it. An order that opens or adds to a position adds a grid of the order type (market within a worst price, limit `Gtc` or post-only `Alo`), the leverage, the margin (notional ÷ leverage, rounded up to the cent; `Isolated margin` for an isolated order) and, when no rail places it, the worst or limit price. An order with exits adds a price rail: stop, entry, take-profit and a trailing stop's activation price (`Trails from 85,000`) placed by their approved prices, each exit's trigger → worst-fill zone shaded, never a live mark; exits on an existing position read `On your position` in place of an entry. A trailing stop follows the mark, so its retracement is read under the rail (`Trails 2% from the best price once the mark reaches 85,000`, or `Trails 1,500` for a fixed distance); without an activation price it has no fixed price and no marker. The rail is decorative, and each exit's exact trigger and worst price, and the trailing stop's retracement, are also read as words. One muted line closes the face: when the approval lapses, or for a reduce-only close its bound (`Worst price up to 80,000 · reduce-only`); a close is the hero and that line, with no grid or rail. Everything else is behind one `Details` disclosure: the headline sentence, which names the mode too (`Long BTC · 0.001 at up to 82,000 · 3× isolated`), every approved term word for word and never rounded (the `Margin mode`, and near.com's 0.07% builder fee, none on a trailing stop and `No builder fee` when the trailing stop is the only exit, among them), and the raw grant and input. A trailing stop alone heads its card `Trailing stop on long BTC`. A cancellation (`perps_order_cancel`) names its order (`Order #123`, headline `Cancel BTC order #123`) over its deadline, and its dismiss button reads `Keep order`. A grant missing, malformed or not matching the stored input offers only Cancel, and `approvalContent` reports it unreadable. Once decided, the card says what Hyperliquid did: placed (each placement filled with its size and average price, resting, waiting for its trigger, or rejected; the trailing stop with its Hyperliquid order number, since it has no client order id), with the average fill on the rail and each exit's answer under it, rejected with Hyperliquid's reason, not signed, cancelled, not cancelled, or waiting for Hyperliquid's answer, which is never resubmitted. It never says executed; a decided card keeps its terms under `Exact terms`. An automation whose grant is a standing `perps_automation` (`automation_create`) leads with one firing as the order card's ticket: a side chip (`Open long`, `Reduce long`, `Close long` or `Add margin`) beside the coin, and the notional, share or exact USDC amount large (`$200.00 notional` with `3× cross`, `50% of the position`, `25 USDC`). Under it, the trigger on a compact gauge with one label (`When liquidation distance < 10%`, `When margin ratio > 60%`, `When funding rate > 0.05%/h`; a rule over any other field reads as its clause in words), then one muted line of limits (`3 runs · until Sep 12`). Everything else is behind one `Details` disclosure: the rule's whole sentence and the deadline, then every term (the order and its worst price, an open's leverage and native exits, or the transfer and its max loss; what it may do to exposure, `Never opens or adds to a position` or that an open acts only while nothing is held on the coin; the checks and the policy service's reread of Hyperliquid, the builder fee on an order, an open's or added margin's region gate), then the raw grant and input. The rule's sentence also names the card for a screen reader. `expanded` opens `Details`, and `onToggleTerms` reports it. The request must carry exactly its grant: a request whose contract differs from the grant, a grant this version cannot read, or a request that does not parse offers only Cancel, and `approvalContent` reports it unreadable. The gauge draws only approved numbers and fixed points, with decimal arithmetic: liquidation distance runs from liquidation at 0% to twice the threshold, margin ratio from 0% to liquidation at 100%, and funding (in percent an hour) from one threshold's width past zero to twice the threshold, with zero marked. The side the rule acts on is shaded. A reading recorded by a firing's decision widens the scale to fit when it falls outside. The drawing is decorative (`aria-hidden`); the trigger and any reading are in words beside it. A margin change's card (`perps_margin_update`) reads its one-shot `perps_margin` grant and uses the same ticket: an `Add margin` or `Remove margin` chip beside the coin and `isolated`, the exact USDC large, where it goes and what it does to the liquidation risk under it, the market and its index, the deadline in its muted line, and `Builder fee: None` under `Details`. It is headed `Add 250 USDC margin to BTC` or `Remove 12.5 USDC margin from BTC`, under a `Perps margin · needs approval` eyebrow, and approved with `Add margin` or `Remove margin`. Once decided it reads `Applied` (Hyperliquid added or removed the exact amount), `Not applied` with Hyperliquid's or Fin's reason (the position's margin is unchanged), or waiting for Hyperliquid's answer, which is never resubmitted. A Solana buy, sale, funding or withdrawal (`solana_buy`, `solana_sell`, `solana_fund`, `solana_withdraw`) reads its one-shot grant, tool-bound like a perps transfer, and every term is the host's own derivation of the call, never the model's words. It is a venue's ticket, as a perps order's is: the token's disc and a title (`Buy BONK`, `Sell BONK`, `Fund your Solana account`, `Withdraw SOL`), then one well of figures, `You pay` (or `You sell`, `You send`), `You get` and `Max loss` (`8% · at least $46.00` for a buy paid in USDC or USDT, the floor in dollars cut at the cent and never rounded up; `8% of the value` otherwise), the bound in the caution ink above 300 basis points, the Intents default. A buy or funding paid in dollars names its debit `USDC or USDT` (`You pay 50.00 USDC or USDT`) with a `From` detail saying it comes from one holding of either that covers it, USDC first, because the source is chosen only when it runs. One the user approved to pay with a coin (`payWith`) names that coin and the most of it it may spend instead (`You pay $50.00 of NEAR`, `From: Your agent wallet's NEAR, at most 22.3125 NEAR`), and so do the perps funding card's `Amount` and `From` and the visual Polymarket funding card's `Pays` side. The band's countdown is the one deadline it shows. A token the chat's reads found a warning on wears its worst one beside the title, from `tokenRisks` (`solanaRisks(thread.items)`, which `FinEntry` passes). SOL itself, which a funding or a withdrawal moves, wears no network badge. `You get` is an estimate (`≈ 1,512,402 BONK`) only where `holdings` prices both sides, a Solana token by `solana:`; otherwise it names the asset. The route (`USDC → SOL (1Click) → BONK (Jupiter)`), a USDC buy's `Top-up` kept as SOL for network fees, the most a transaction pays the network (0.001005 SOL: the base fee and the priority-fee ceiling, from the reviewed constants), that a buy or a funding opens the agent's Solana account if it is new, the shortened token address with a button that copies it whole, the token program and the one execution sit behind Details. The token's symbol, name and icon come from the resolver by `solana:`; a token it does not know reads as its shortened mint, and a token without an icon wears its first letter on a colour taken from its mint. A grant missing, malformed, for another tool, for more than one execution or not matching the stored input offers only Cancel, and `approvalContent` reports it unreadable. Once decided, the eyebrow and status line follow the journal in Solana's words: `Funding your Solana account` while the 1Click funding leg works, `Swapping on Solana` once that leg's receipt has settled, `Sending back to your wallet` for the leg that returns USDC, `Done`, `Partly done: SOL is in your Solana account` (the reason the next step never started is the outcome's own, when it states one) or, for a sale or a withdrawal whose SOL 1Click took without completing the transfer, `Partly done: SOL is with 1Click` (its transfer to 1Click landed and the outcome left no SOL in the account, so it is with 1Click until it refunds it), `Didn't run (expired)`, or waiting for Solana, never to be approved again. A partial sale or withdrawal whose outcome says neither reads `Partly done` and sends the user to check their Solana account; it never guesses where the SOL is. A sale that asked to keep its SOL is `Done` although its outcome is partial by design. A `solana.reconciled` answer replaces the call's own unconfirmed result, as for perps, so the card moves from waiting to its final state live and on replay. An occurrence under a standing grant keeps a financial tool card and its result receipt even when it opens no approval in this chat: pending, partial, refused and not executed results never inherit the generic completed check. A Solana buy or sale approved once for every time an automation fires is an `automation_create` approval whose stored definition carries a `solana_buy` or `solana_sell` contract, and the card reads it as the automation it is: the eyebrow says `New automation · needs approval`, the ticket's title is the rule's own sentence (`Every day at 9:00 AM, buy 20.00 USDC of BONK`, `When BONK price is at or above $0.00003, sell 50% of your BONK for USDC`: every threshold digit is shown, so `$1.804999` never becomes `$1.80`) and the primary is `Approve automation`. Its figures are the loss bound `each time` (in the caution ink above 300 basis points) and `Times` (`Up to 30 times · until Oct 11, 2026, 12:00 PM`). Behind Details: what each run pays or sells (a sale is a share of what the account holds when it runs, never today's amount), the SOL top-up, for a condition `Checks` (how often, and that a move between two checks can be missed) and `Execution` (the market price when it runs, not the level in the condition), the route and the fees, the token address and program, the signing window and how to revoke. A condition names the token, never its mint. The grant is drawn only when the host's contract and the stored definition agree on every term and the rule is one a standing Solana grant may have (a polled `jupiter.token_price` of the grant's own token, no event wake or exit watch); otherwise the card offers only Cancel and `approvalContent` reports it unreadable. Once decided it ends as any saved automation's does, since approving trades nothing. Its Exact terms control remains available even with `automationTerms="summary"`, showing the complete stored definition the owner signs, including the rule, grant, limits and signing window. With `predictionVariant="visual"`, pending Polymarket funding and order approvals keep the headline, hero, risk notice and decisions visible. Funding's three step-1 tiles move under `Details`; an order's payout, implied chance and lifetime sit under `Details · payout, chance, lifetime`. Exact terms retains its existing disclosure. Decided funding cards and observed orders start closed to their title, status chip and key figure (delivered USDC or wallet pUSD, matched shares, or a settled receipt's paid/proceeds and average). Opening reveals the existing figures, stages, rows, receipt and notes. Bridge failures, held / refunded / refused funding, failed trades, rejected orders and uncertain states keep their explanation in the summary. An open order's Cancel order and a problem state's Check again stay outside the fold. Declined / expired funding one-liners and order stopped stages, submitting and blocked states are unchanged. The `default` variant is unchanged. Visual funding adds `prediction-fund-card-fold`, `prediction-fund-card-fold-summary` and `prediction-fund-card-fold-panel`; visual orders add `prediction-order-card-fold`, `prediction-order-card-fold-summary` and `prediction-order-card-fold-panel`, alongside the existing hero-side, tile, meter, rows, note and timeline hooks under the corresponding prefix. Each fold is a keyboard-operable button; reduced motion removes chevron transitions. A grid's card (`grid_create`) reads the grid contract the owner signs, never the model's words: its pair and range, a `GridBand` drawn to scale (the price now as a dot when `holdings` prices both assets, an estimate only), what one cycle earns at least (the sale's minimum receive less the buy's cost, before fees), the quote its buys use at the start, each order's size, and what happens outside the range, where the idle cells never place an order. Review terms lists every level, the cells that start buying, what it uses at the start and when the grid ends; the button reads Approve grid, and the footnote counts the orders it places at the start (`3 orders`). A grid contract this version cannot read offers only Cancel. Once decided, the band reads `Grid · started` (or paused, resumed, stopped for the other grid tools) and the line says where the grid stands, never that a trade executed. Parts: `approval-card-band` (the status band), `approval-card-body`, `approval-card-headline`, `approval-card-terms`, `approval-card-actions` and `approval-card-evidence` (the exact terms; on a pending perps order, cancellation, margin change or automation, the `Details` disclosure that holds them). A perps order's, cancellation's, margin change's or automation's ticket adds `approval-card-hero` (side, coin and size); an order that opens and a margin change add `approval-card-figures` (the grid), an order adds `approval-card-rail` (the price rail, when it has exits) and `approval-card-footnote` (its one muted line); a perps automation adds `approval-card-trigger` (the trigger and its gauge) and `approval-card-limits` (its one limits line). A Solana ticket uses `approval-card-hero` (the disc and title), `approval-card-figures` (what it pays and gets and its loss bound, the caution one carrying `data-tone="caution"`) and `approval-card-details` (the rest). Inside, `decision-countdown` is the time left to decide and `execution-swaps` a multi-swap execution's swaps. > [!NOTE] > Below 480px wide, the terms open in a sheet portalled to the end of `body`. Theme it page-wide: > `--fin-*` variables on `:root`, dark mode on `html`, and CSS by `data-fin-ui` rather than a > selector under the card. ### `ApprovalRecovery` What an approved request offers once part of it could not run, for an app that draws its own approval card: the same fresh review `ApprovalCard` offers (a higher price limit, a retry, the remaining transfers), resuming only the failed branch. Completed actions stay complete, and the new terms are checked again and signed by the owner as any approval is. It draws nothing until every claimed action has ended, or when nothing is left to recover. | Prop | Type | What it does | |---|---|---| | `approval` | `ApprovalView` | The approval as the thread holds it. | | `approvals` | `ApprovalHandlers` | The handlers `FinEntry` takes: `onReviewRemaining` with its states, errors and evidence. Without `onReviewRemaining` it draws nothing. | | `outcome` | `ToolCallOutcome` | The linked call's result (`toolForApproval(thread, approval)?.outcome`). | | `running` | `boolean` | The linked call is still running. | | `ended` | `boolean` | A run boundary came after the linked call (`runEndedAfter`). | | `execution` | `ExecutionView` | `executionForApproval(thread, approval)`. | | `className` | `string` | Classes for its block. | `approvalRecovery(props)` returns what it would offer (the actions, the bound they ran under, and the review handlers), or `null`: use it to leave out a retry of your own while the review is offered. ### `ApprovalExpansionProvider` Keeps one approval card's terms open at a time inside it. Wrap your transcript in one. Its only prop is `children`. ### `ContractTerms` Every term of a NEAR Intents contract: the actions in their approved order, then the bounds, allowance and validity. The approval card draws it; place it yourself on an automation's page. | Prop | Type | Description | | --- | --- | --- | | `contract` | `NearIntentsContract` | An approval's `contract` of type `near_intents_transfer`, or an automation's grant. | | `density` | `"card" \| "compact"` | `card` lists every fact; `compact` is a page's summary. | | `noun` | `"execution" \| "run"` | `execution` in chat, `run` for an automation. | | `executionsUsed` | `number` | Executions that used allowance, on an automation's page. | | `revokedAt` | `string \| null` | When the grant was revoked. | | `spendProgress` | `string \| null` | Spend against the cap, such as `2 of 5 USDC spent`. | | `holdings` | `AgentHolding[]` | The wallet's balances, so a share-of-balance term shows today's amount. | | `now` | `number` | The clock; stories and tests pin it. | | `className` | `string` | Classes for the root. | An `AgentHolding` is a holding by `tokenId`, with its `decimals` and its `amountRaw` in the smallest unit. A `PricedHolding` adds its price, as built under `FinEntry`. ### `GridBand` A grid drawn to scale: a tick at every level, each cell tinted by its side (buys green, sells yellow), a dashed tick where no order rests, the price now as a dot, and a dot over each cell that completed a cycle. Every position comes from the exact prices. The drawing is `aria-hidden`; a sentence beside it says the same. A grid's `ApprovalCard` and `GridCard` draw it; place it yourself from `gridView(grid).band` or `gridApprovalView(approval).band`. | Prop | Type | Description | | --- | --- | --- | | `levels` | `readonly string[]` | The levels, lowest first: quote units per one base unit, exact decimals. | | `cells` | `readonly GridBandCell[]` | One per cell, lowest first: `{ side, resting?, cycles? }`, its `side` `buy`, `sell` or `idle`. A cell that is not `resting` draws dashed; one with `cycles` carries a fill dot. | | `price` | `string \| null` | The price now, an exact decimal in the same unit: the now dot. None without it. | | `unit` | `string` | What the prices are in, such as `USDC per ZEC`, for the sentence beside the drawing. | | `size` | `"sm" \| "lg"` | `lg` (the default) with its price labels; `sm`, a strip for a compact row. | | `className` | `string` | Classes for the drawing. | | `classNames` | `{ rail?, ticks?, now?, labels? }` | Classes for its parts. | Parts: `grid-band-rail` (with each cell's zone), `grid-band-ticks` (with the fill dots), `grid-band-now` and `grid-band-labels`. Each tick carries `data-tick` (`buy`, `sell`, `both` or `gap`) and each fill dot `data-fill`. ### `PendingApprovalChip` A chip above your composer naming the proposal that waits for the user, with its clock. | Prop | Type | Description | | --- | --- | --- | | `pending` | `PendingApproval` | The proposal: its `approvalId`, its `headline` and when it `expiresAt`. | | `onOpen` | `() => void` | Scroll its card into view. | | `now` | `() => number` | The clock; stories and tests pin it. | | `className` | `string` | Classes for the root. | `pendingApprovals(thread)` lists what waits, and `contractHeadline` words one as the card does. ### `QuestionCard` The agent's questions, one at a time. A single choice answers with one tap; a multiple choice, an amount or the user's own words wait for Send, and Skip passes over the question on screen. After the last, it sends every answer given, or skips the card when the user skipped every question. Answered, it shrinks to one line. An option the agent marked `recommended` carries a Recommended badge, and is never chosen for the user. A question with `amount` draws an amount picker instead of choices: the figure, a slider from `amount.min` to `amount.max` in steps of `amount.step`, its presets as buttons, and "Use $100". A preset sends its value; any other amount sends `customText`, its exact decimal. Amounts are exact decimals throughout; the slider counts whole steps. | Prop | Type | Description | | --- | --- | --- | | `question` | `Question` | The questionnaire: `thread.questions[questionId]`. | | `onAnswer` | `(questionId, answer) => void` | The user answered or skipped. Send it with `questions.answer`. | | `busy` | `boolean` | An answer is being sent; holds the buttons. | | `error` | `string \| null` | Fin's refusal of the last answer, until dismissed. | | `onDismissError` | `() => void` | The user dismissed the refusal. | | `variant` | `QuestionCardVariant` | `list` (the default): chips, or one row per described choice. `cards`: two to four described choices side by side as cards (ticked in a multiple choice), rows again when the card is narrower than 480 px, and number keys 1–9 that answer while the card has focus, never while the user types. The key caps hide on a touch screen. | | `className` | `string` | Classes for the card, or its answered line. | | `classNames` | `{ header?, prompt?, options?, amount?, error?, actions? }` | Classes for its parts. | Parts: `question-card-header` (the step line), `question-card-prompt`, `question-card-options`, `question-card-amount` (the amount picker), `question-card-error`, `question-card-actions`. ## Result cards The cards a run's results draw. Send `RENDERED_CARDS` as `context.renders` when starting a run, and the reply leaves these facts to them. Add `placement` to draw a read's card only where the reply places it, or `show` to draw it where the agent's `show_cards` call stands, as the agent finds what the question needs: draw each turn from `threadTurns(thread)` ([The model](/react-model#the-transcript)), and these cards where its `card` and `cards` parts name them. Send `context.country` from your server's edge geolocation with every message too; [Tokenized stocks](/concepts#tokenized-stocks) explains the country and purchase restrictions. ### `AutomationCard` A saved automation: its status, what it waits for, whether it may trade without asking, and when it ends. Its Manage link goes to `routes.automation(id)`. | Prop | Type | Description | | --- | --- | --- | | `receipt` | `AutomationReceipt` | What `automation_create` or `automations_edit` returned after commit. | | `automation` | `Automation` | The current owner-scoped read; an older version cannot overwrite a committed edit receipt. | | `now` | `number` | The clock for times and validity; stories and tests pin it. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, title?, details?, action?, hero?, trigger?, runs? }` | Classes for its parts. | Parts: `automation-card-header`, `automation-card-title`, `automation-card-details`, `automation-card-action` (the Manage link). A perps automation adds `automation-card-hero` (what one firing does, with its bound), `automation-card-trigger` (the trigger's gauge, with the reading the latest run's decision recorded when its evidence holds one) and `automation-card-runs` (the grant's runs used of its maximum, and the latest run's state, or when it ends if it has not run). Edit receipts show the committed definition version and webhook sender setup notice. Until the complete current read arrives, they do not reconstruct the rule or claim live financial authority. Keep the page and thread on the same resource cache, invalidate that cache on a completed edit (also when replayed after reconnect), and refetch by `automationIdsOf(thread.items)`. The receipt retains its committed revision even if a later edit has advanced the current definition. A receipt's `approvalPolicy:"standing_contract"` describes signed terms at commit, not policy acknowledgement or live signing authority. Recovery reads only the retained receipt; the separate durable transition carries policy acknowledgement. Read current grant status before claiming that unattended execution is active. ### `PerpsFiringCard` One firing of a perps automation in its conversation: the sealed reduce order the automation's run placed (`perps_order_place`), drawn beneath that run's activity line. `FinEntry` draws it for a call the thread stamped with its run's automation; pass the automation by id in `automations` (`automationIdsOf(thread.items)` includes it). | Prop | Type | Description | | --- | --- | --- | | `item` | `ToolItem` | The run's `perps_order_place` call, with Hyperliquid's answer. | | `automation` | `Automation` | The automation whose run it was, when read: the card counts the run and shows why it fired. | | `now` | `number` | The clock for times; stories and tests pin it. | | `className` | `string` | Classes for the card. | | `classNames` | `{ band?, body?, hero?, rail?, trigger?, status? }` | Classes for its parts. | It reads the order and Hyperliquid's answer from the call itself: the order's hero (`Reduce long`, the filled size, `Filled at an average 74,980.5 USDC`), and the fill on a rail between the order's bound (`Floor 74,250 · never sold below` for a long) and, when the decision recorded one, the mark (`Mark 75,000 · at the check`). With the automation it adds `Run 1 of 3` (only when this call's run is the automation's latest and the order was placed: the grant's executions used of its maximum) and `Why it fired` on the trigger's gauge, with the reading the run's decision recorded. A figure the card was not given is left out. Placed and filled, Hyperliquid's sentence stays for a screen reader; any other answer is in words. Parts: `perps-firing-card-band`, `perps-firing-card-body`, `perps-firing-card-hero`, `perps-firing-card-rail`, `perps-firing-card-trigger`, `perps-firing-card-status`. ### `WalletCard` The agent wallet as a balance read found it: the total and each asset, valued exactly and rounded once. When the read says how each price was found (`priceStatus`), the total is what is priced, with the count of unpriced assets under it ("1 unpriced"), and a row whose price is carried, the owner's last trade or missing says so under its value ("Carried", "Last trade", "No price"). A read without `priceStatus` draws as before: no total while any asset is unpriced. Its link goes to `routes.assets()`. | Prop | Type | Description | | --- | --- | --- | | `reading` | `WalletReading` | The read's balances, priced where a price was known, each with how its price was found where the read says. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, holdings?, action? }` | Classes for its parts. | Parts: `wallet-card-header` (with the total and the unpriced count), `wallet-card-holdings`, `wallet-card-action`. ### `OrdersCard` Limit orders, one line each: what it buys or sells and at what price, where it stands, and when it lapses. A fill never reads as done while its payout can change. Its "Manage orders" link goes to `routes.orders()`, your page for the user's limit orders, where a cancel button calls Cancel a limit order. | Prop | Type | Description | | --- | --- | --- | | `orders` | `readonly LimitOrderView[]` | The orders, each with its fill and payout status. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, orders?, action? }` | Classes for its parts. | Parts: `orders-card-header` (the count), `orders-card-orders`, `orders-card-action`. ### `PredictionOrdersCard` The owner's retained Polymarket orders, with exact approved prices and quantities, observed matched/unmatched shares and settlement status. `FinEntry` draws this for `prediction_orders` when `resultCards` includes `predictions`. An empty result shows that this page has no orders. The card never fetches or cancels an order itself. | Prop | Type | Description | | --- | --- | --- | | `orders` | `readonly PredictionOrderRow[]` | Each row contains `operationId`, the approved `order` and its latest `observation`. | | `nextAfterId` | `string \| null` | Optional tool-page continuation id. A non-null id shows that more orders are available; `onDraft` adds a next-page draft button. | | `onDraft` | `(message: string) => void` | Optional cancellation draft for an open, partially matched or uncertain order, or next-page request. The host puts it in the composer; it executes neither request. | | `variant` | `"default" \| "visual"` | `visual` groups Open and Needs checking orders above a closed Finished fold. Each row starts closed to side, quantity, limit, status chip and market question; opening reveals the thin partial-fill meter and figures. Failure / uncertainty explanations and Cancel order remain visible without opening a row. `FinEntry` passes its `predictionVariant`. Defaults to the original rendering. | | `now` | `number` | The clock the visual header's "checked" time is read against. Defaults to `Date.now()`. | | `defaultOpen` | `boolean` | Initially opens every visual order row and the Finished group. Defaults to `false`; no effect on the default variant. | | `className` | `string` | Classes for the root. | | `classNames` | `PartClassNames` | Classes for the named parts. | Parts: `prediction-orders-card-header`, `prediction-orders-card-orders`, `prediction-orders-card-order`, `prediction-orders-card-terms`, `prediction-orders-card-status`, `prediction-orders-card-actions`, `prediction-orders-card-pagination`. The visual root carries `data-fin-variant="visual"` and adds `prediction-orders-card-group`, `prediction-orders-card-figures`, `prediction-orders-card-meter`, `prediction-orders-card-fold`, `prediction-orders-card-fold-summary` and `prediction-orders-card-fold-panel`. The header keeps open / needs-checking counts and the checked time visible. Live and partly filled orders belong to Open; uncertain, cancel-unconfirmed, settling / settlement-unconfirmed and cancelled / expired orders with unsettled or failed trades belong to Needs checking. Everything else belongs to Finished. Show older orders and the empty state are unchanged. ### `GridCard` A grid of resting limit orders as it runs, beside the message that started, changed or read it: its state badge, what it earned, how many buys and sells rest now and the base it holds, its `GridBand` with the cells that filled, its completed cycles, and its controls. Pause shows on a running grid, Resume on a paused one, Stop until it ends, each only when you pass its handler; your server then calls Pause, Resume or Cancel a grid. | Prop | Type | Description | | --- | --- | --- | | `grid` | `Grid` | The grid as a grid tool or Get a grid returned it. | | `variant` | `"full" \| "compact"` | `full` (the default), or `compact`: one row with its earnings, a strip of its band and what rests, for a list of several. | | `price` | `string \| null` | The price now, quote per one base as an exact decimal, when your app has it: the band's now dot. | | `now` | `number` | The clock for the grid's day count; stories and tests pin it. | | `busy` | `GridAction \| null` | The control being sent now: its button waits and the others hold. | | `onPause` | `() => void` | The user pressed Pause. Without it, no Pause button. | | `onResume` | `() => void` | The user pressed Resume. Without it, no Resume button. | | `onCancel` | `() => void` | The user pressed Stop; confirm it first if your app asks. Without it, no Stop button. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, title?, band?, stats?, fills?, actions? }` | Classes for its parts. | Parts: `grid-card-header` (with the state badge), `grid-card-title`, `grid-card-band`, `grid-card-stats` (the figures, or a compact card's line), `grid-card-fills` (its completed cycles) and `grid-card-actions`. The root carries `data-state`, the grid's `state`, and `data-variant`. ### `ContactsCard` The user's saved contacts as a `contacts_list` lookup found them, one row each, as a contacts page shows them: the name, the address shortened with a button that copies it whole, and the network. Five show at first and a button shows the rest. When the user has none saved, it says so. Its link goes to `routes.contacts()`, your app's own contacts page; unset, it draws no link. It draws only the contacts your server sent as `context.contacts` with that message, and none for a lookup right before a payment approval, whose card shows the full address. | Prop | Type | Description | | --- | --- | --- | | `lookup` | `ContactsLookup` | The contacts the lookup returned, how many `matched`, whether it was `truncated`, and what it searched for (`search`, `network`). | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, contacts?, more?, action? }` | Classes for its parts. | Parts: `contacts-card-header` (the count, and what was searched for), `contacts-card-contacts`, `contacts-card-more` (shows the rest), `contacts-card-action`. ### `PriceCard` One asset's price over the window a `market_history` read covered: the price and its change, a chart, and the window's figures (its return, biggest drop with its dates, best and worst day) exactly as the tool reported them, with the source and when it was read. The chart's readout starts pinned to the low of the biggest drop when the read included the daily `series`; a hidden "History point" slider moves it for the keyboard. With `loadHistory`, range tabs (1W, 1M, 3M, 1Y) redraw the chart and its change over another window your server loads; the tool's figures stay with the tool's own window. Prices become pixel positions only to draw the line; every figure is an exact decimal. `FinEntry` draws it when `resultCards` includes `market`. | Prop | Type | Description | | --- | --- | --- | | `history` | `PriceHistory` | One asset's history, from `toolBlock` (`kind: "price"`). | | `loadHistory` | `PriceHistoryLoader` | `({ assetId, range, signal }) => Promise`: loads a `PriceRange` for the range tabs, oldest first; reject when it is unavailable. Without it, no tabs. `PriceCard` asks for 1W to 1Y; a range type that also names `1D` lets one loader serve a card of your own that offers the day. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, chart?, ranges?, figures?, source? }` | Classes for its parts. | Parts: `price-card-header` (the price and its change), `price-card-chart`, `price-card-ranges`, `price-card-figures`, `price-card-source`. ### `ComparisonCard` Several assets from one `market_history` read side by side: each one's trend line, price now, move today (since the last daily price), return over the window and worst drop, as the tool reported them. Assets the read could not reach are named beneath. It ranks nothing; the reply says which did best. `FinEntry` draws it when `resultCards` includes `market`. | Prop | Type | Description | | --- | --- | --- | | `comparison` | `MarketComparison` | The read's assets, from `toolBlock` (`kind: "comparison"`). | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, table? }` | Classes for its parts. | Parts: `comparison-card-header` (the assets and the source), `comparison-card-table`. ### `PredictionsCard` The events a `prediction_markets` search found, each linked to its venue page with its end date and volume, and up to four of its markets. For an open search a market shows the chance traders price on its first outcome (its price, read as a percentage, beside a bar) and the bid-ask spread, or Thin when the tool marked the quote weak; for a settled search (`status: "settled"`) it shows the outcome the market resolved to, or Not settled, and the day it closed. Days are the venue's, in US Eastern time and marked ET ("Ends Dec 9, 2026 ET"), wherever the reader is. Markets the tool left out are counted beneath each event, and the note says a price is a market-implied chance, not a forecast (or that settled prices are final), and that the research read places no order. It ranks nothing and suggests no trade. A search that found no event draws nothing. `FinEntry` draws it when `resultCards` includes `predictions`. `variant="visual"` makes the header a card-level fold, initially open, with the query, source, read time and event count. Events start closed to their question, leading outcome with a thin green bar and chance, end date, volume and market count. Opening one shows its first four markets; “N more markets” opens any remaining returned markets. Only the leader is green, and a weak quote is marked on its row without opening quote details. “Quote details · spreads” holds the bid–ask figures and explains that a spread above $0.10 deserves little weight. Each event retains its venue link and the count of markets omitted from the read. Settled searches name resolved outcomes instead of showing percentages. The original table remains the default. Visual cards state monetary figures to four significant digits. | Prop | Type | Description | | --- | --- | --- | | `search` | `PredictionSearch` | The search's events, from `toolBlock` (`kind: "predictions"`). | | `variant` | `"default" \| "visual"` | Original table (default), or outcome-bar rows. | | `defaultOpen` | `boolean` | Visual only: initially opens the first event (default `false`); the card-level fold always starts open. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, events?, note? }` | Classes for its parts. | Parts: `predictions-card-header` (the query and the source), `predictions-card-events`, `predictions-card-note`. Visual-only styling hooks: `predictions-card-event`, `predictions-card-outcome-row`, `predictions-card-bar`, `predictions-card-spread`. Visual roots carry `data-fin-variant="visual"`. Visual folds expose `predictions-card-fold`, `predictions-card-fold-summary` and `predictions-card-fold-panel`; `data-fin-fold="card"`, `"row"` or `"quiet"` identifies the level. Summary buttons support Enter and Space; mounted panels retain nested disclosure state. ### `PredictionMarketCard` One market a `prediction_market` read found: its question, where it resolves from, its end date (in US Eastern time, marked ET) and volume, both outcomes with the chance and share price each implies, and the venue's own settlement rules folded under Settlement rules, with the note that clarifications the venue posts later are not shown. A closed market shows the outcome it resolved to and the day it closed in place of prices, or says it has not cleanly settled when its final prices name no winner; a market the venue is not trading but has not closed reads Inactive, never closed or settled. Its footer marks the result as research with no order placed and links to the venue page. `FinEntry` draws it when `resultCards` includes `predictions`. `variant="visual"` starts closed to the question, Yes/No split, status, end date and source. Both chances and per-share prices remain in the split's legend. Opening the card adds volume, liquidity, whether the market accepts orders, its resolution source and the venue link. Settlement rules are a nested quiet fold. A missing price is not invented; a settled market names its winner instead of showing prices. Closed and inactive markets keep their status and explanation visible even while closed. The default variant keeps its original tiles and settlement-rules Disclosure. | Prop | Type | Description | | --- | --- | --- | | `market` | `PredictionMarketDetail` | The market, from `toolBlock` (`kind: "predictionMarket"`). | | `variant` | `"default" \| "visual"` | Original outcome tiles (default), or Yes/No split. | | `defaultOpen` | `boolean` | Visual only: initially opens the card's facts (default `false`); rules remain closed. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, outcomes?, facts?, rules?, footer? }` | Classes for its parts; `facts` is visual-only. | Parts: `prediction-market-card-header` (the question, the source and the facts), `prediction-market-card-outcomes`, `prediction-market-card-rules`, `prediction-market-card-footer`. Visual-only parts: `prediction-market-card-facts`, with additional styling hooks `prediction-market-card-split` and `prediction-market-card-legend`. Visual folds expose `prediction-market-card-fold`, `prediction-market-card-fold-summary` and `prediction-market-card-fold-panel`, with `data-fin-fold` identifying card and quiet levels. ### `PredictionPreviewCard` What a stake on one outcome would buy against the venue's displayed offers, as a `prediction_preview` walk found it: the shares, the average price and what they pay if the outcome happens ($1 a share), with how fully the book took the stake (Fully placed, Book too thin, Below minimum or No offers) and, when it did not, how much found no offer or the venue's minimum. Shares and the payout are rounded down to the cent, so the card never shows more than the walk bought. The note says when the order book was read, that fees are not included, that it is not a quote, and that no order was placed. `FinEntry` draws it when `resultCards` includes `predictions`. `variant="visual"` starts closed to “$X on outcome → N shares”, the depth chip, average price, payout if right, source and read time. A thin book's unplaced amount and a below-minimum explanation with its unplaced amount remain visible in the summary. Opening the card adds the fill meter (green is reported cost, red is unspent stake), both figures in its legend, and best-ask, worst-price and book-level tiles. The warning records the read time, “not a quote” and fees not included. Meter width uses exact decimal arithmetic, not floating-point money. Stated amounts are cut to four significant digits, never rounded up. No orders are placed. | Prop | Type | Description | | --- | --- | --- | | `preview` | `PredictionPreview` | The walk, from `toolBlock` (`kind: "predictionPreview"`). | | `variant` | `"default" \| "visual"` | Original figures (default), or fill meter and stat tiles. | | `defaultOpen` | `boolean` | Visual only: initially opens the fill meter, tiles and preview warning (default `false`). | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, figures?, meter?, legend?, warning?, footer?, note? }` | Classes for its parts; meter, legend, warning and footer are visual-only. | Parts: `prediction-preview-card-header` (the stake and how fully it was placed), `prediction-preview-card-figures`, `prediction-preview-card-note`. Visual-only parts: `prediction-preview-card-meter`, `prediction-preview-card-legend`, `prediction-preview-card-warning`, `prediction-preview-card-footer`; tiles expose the `prediction-preview-card-tile` styling hook. The visual fold exposes `prediction-preview-card-fold`, `prediction-preview-card-fold-summary` and `prediction-preview-card-fold-panel`, with `data-fin-fold="card"`. ### `SettlementReceipt` One swap's settlement as the journal recorded it: what was received or returned. | Prop | Type | Description | | --- | --- | --- | | `receipt` | `EventPayload<"intents.settlement">` | The journal's settlement record. | | `className` | `string` | Classes for the receipt. | | `classNames` | `{ header?, details? }` | Classes for its parts. | Parts: `settlement-receipt-header` (the confirmation line), `settlement-receipt-details`. ### `SolanaReceipt` What a Solana buy, sale, funding or withdrawal did, drawn under its approval from the call's own outcome (`FinEntry` places it), its figures in one well as the approval's ticket draws its terms. Every figure is the host's record, read with exact arithmetic: what was paid and received, the average price that came to (paid ÷ received, in dollars as every token price reads, `$104.20` or `$0.0₄3306`, or in SOL), the network fees the landed transactions paid, and any SOL the operation left in the Solana account, then a row per transaction it signed (`Swap`, `Send back`) with where it stands: landed, landed with an error, expired before it landed, or not confirmed yet. A transaction links to your explorer through `routes.transaction("solana", signature)`; without one the signature is shortened with a button that copies it whole. The title says what it was (`Bought BONK`, `Sold BONK`, `Funded your Solana account`) once it is done, and a neutral noun (`Your BONK buy`) while it is not; the badge is the outcome's own status. A buy that only funded the account, or a sale whose SOL stayed in the account, offers its next moves as buttons (`Buy BONK with it`, `Move it back as USDC`) that send a message as the user's next one through `onSend`; they move nothing. A sale that asked to keep its SOL is `Done`, although its outcome is partial by design. | Prop | Type | Description | | --- | --- | --- | | `receipt` | `SolanaReceiptView` | The receipt, from `deriveSolanaReceipt(approval, outcome)`: `null` for an outcome without a Solana detail, so draw nothing then. | | `onSend` | `(message) => void` | Send the message as the user's next one. Without it, no follow-up buttons. `FinEntry` passes its `onSend`. | | `disabled` | `boolean` | Holds the follow-ups while a run works or a message is on its way. `FinEntry` passes it from `sendDisabled` and the run's state. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, figures?, transactions?, actions? }` | Classes for its parts. | Parts: `solana-receipt-header` (the title and its status), `solana-receipt-figures`, `solana-receipt-transactions`, `solana-receipt-actions` (the follow-ups). ### `HoldingsCard` The agent wallet as a balance read found it, as a breakdown: a donut of each asset's value beside a list, largest first, of each asset's amount, exact value and share of the total. Shares are rounded once, to a tenth of a percent, from integer cents. An asset without a price is listed without a value and left out of the total, which says so. When the read says how each price was found (`priceStatus`), a row whose price is carried, the owner's last trade or missing names it after its amount ("· Carried", "· Last trade", "· No price"), and the unpriced are counted in the donut under the asset count ("1 unpriced") rather than marked with a "+". Its link goes to `routes.assets()`. `FinEntry` draws it in place of `WalletCard` with `walletVariant="holdings"`. | Prop | Type | Description | | --- | --- | --- | | `reading` | `WalletReading` | The read's balances, priced where a price was known, each with how its price was found where the read says. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, chart?, holdings?, action? }` | Classes for its parts. | Parts: `holdings-card-header`, `holdings-card-chart` (the donut and the total), `holdings-card-holdings`, `holdings-card-action` (the Assets link). ### `VaultsCard` The curated vaults an `earn_vaults` read listed, one each: the vault, its share token and chain, what it pays with, its minimum, its share price and its three fees verbatim, the rate its provider states now ("5.40% APY now (Yield.xyz) — variable, not guaranteed", worded as the approval card's vault yield note), and how many vaults are not tradable right now. A vault whose rate could not be read shows none, and the card never projects a yield of its own. Beside the warning that each vault is a third-party strategy whose value can fall, it says a rate is the provider's figure now and can change, or that no live rate is available when no vault has one. Deposit moves nothing: it hands your composer a message ("Deposit 1,000 USDC into Gauntlet USDC", the largest power of ten of the payment asset the wallet holds, or no amount when it holds less than one) for the user to edit and send; the deposit itself is an ordinary swap they approve. `FinEntry` draws it when `resultCards` includes `vaults`. | Prop | Type | Description | | --- | --- | --- | | `earn` | `EarnVaults` | The vaults, from `toolBlock` (`kind: "vaults"`). | | `holdings` | `PricedHolding[]` | The agent wallet's holdings, to name a Deposit's amount. `FinEntry` passes the `holdings` of its `ApprovalHandlers`. | | `onDeposit` | `(message) => void` | Put the message in your composer. Without it, no Deposit buttons. `FinEntry` passes `onDraft`. | | `disabled` | `boolean` | Holds Deposit while a run works. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, vaults?, note? }` | Classes for its parts. | Parts: `vaults-card-header`, `vaults-card-vaults`, `vaults-card-note` (the risk and rate note). ### `TokenCandidatesCard` The tokens a `solana_token_search` found, to choose between: the card is the question (`Which WIF?` when two of the candidates it offers first share a symbol), and the agent asks no other. First the candidates that share the name or symbol asked about, those Fin would buy before those it wouldn't, verified first and then by the liquidity in their pools, deepest first; the rest of what the search found waits behind **Show N more** (`searchContenders(search)` orders them). A ticker is not unique on Solana, so each row carries what tells the candidates apart: the token's disc, name and symbol, its mint shortened with a button that copies it whole, the venue's **Verified** mark, and one warning chip only where Fin's checks raised a flag (never a mark that says it is safe). **Use this one** sends a message naming the token and its whole mint as the user's next one; it approves nothing. The name links to `routes.asset`. A search that found nothing draws nothing. `FinEntry` draws it when `resultCards` includes `solana`. | Prop | Type | Description | | --- | --- | --- | | `search` | `SolanaTokenSearch` | The search, from `toolBlock` (`kind: "tokenCandidates"`): the query, whether it was `ambiguous`, the candidates and where they were read. | | `onSend` | `(message) => void` | Send the message as the user's next one. Without it, no Use this one buttons. `FinEntry` passes its `onSend`. | | `disabled` | `boolean` | Holds the buttons while a run works or a message is on its way. `FinEntry` passes it from `sendDisabled` and the run's state. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, candidates?, more? }` | Classes for its parts. | Parts: `token-candidates-card-header` (the question and the source), `token-candidates-card-candidates`, `token-candidates-card-more` (Show N more). Inside, `mint-address` is a mint beside its copy button. ### `MemecoinsCard` The sampled Solana candidates a `memecoins_top` read ranked for one lane and window, as `ComparisonCard` lists coins: a title line (`Trending memecoins`, with `Jupiter` and the time of the read) and ranked rows of rank, disc, name and symbol, price (four significant digits below a dollar) and the move over the window, with one warning chip only where Fin's checks raised a flag. A row whose symbol another row shares shows its shortened mint. On a narrow card the move sits under the price. Seven rows show and the rest wait behind **Show more**. A row opens in place, one at a time, as the activity line's steps do (a button that names the row and the region it controls, by keyboard too): the token's last day as a chart (an hour a point, read through `loadToken`), its market cap, liquidity, 24-hour volume, holders (with `loadToken.token`) and age, every warning it carries, its mint with a copy button, **Open token page** (`routes.asset`) and **Buy…**, which sends a message naming the token by its mint through `onSend` (none for a token Fin will not buy, whose warning says why). The row's reads are kept for the card's life, and one that failed is asked again when the row opens again. A list with no rows draws nothing. `FinEntry` draws it when `resultCards` includes `solana`. `list` can additionally carry classification, evidence gaps, source coverage and a next-page cursor. Preserve those facts when composing a broader discovery page: an unclassified launch is not a confirmed meme, and an activity rank is not a buy recommendation. The read-only `solana_token_history` tool contributes research activity without a separate result card. | Prop | Type | Description | | --- | --- | --- | | `list` | `SolanaTokenList` | The ranked list, from `toolBlock` (`kind: "memecoins"`): its `lane`, `interval`, `items` and source. | | `loadToken` | `SolanaTokenLoader` | Reads an open row's chart (`chart`) and, optionally, its holders (`token`). Without it an open row shows the list's own figures, its warnings and its actions. `FinEntry` passes its `loadSolanaToken`. | | `onSend` | `(message) => void` | Send an open row's Buy… message as the user's next one. Without it, no Buy…. `FinEntry` passes its `onSend`. | | `disabled` | `boolean` | Holds Buy… while a run works or a message is on its way. `FinEntry` passes it from `sendDisabled` and the run's state. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, tokens?, detail?, more? }` | Classes for its parts. | Parts: `memecoins-card-header`, `memecoins-card-tokens` (the rows), `memecoins-card-detail` (an open row), `memecoins-card-more`. ### `SolanaTokenCard` One token a `solana_token` read found, as `PriceCard` draws a coin: `BONK price` with the mint shortened beside its copy button, the price (four significant digits below a dollar) and the day's move in dollars and percent, the token's warnings as one row of chips only where Fin's checks raised any (`Unknown risk` first when Fin could not read its setup, then each flag, the ones that refuse a buy in the danger tone), its market cap, liquidity, 24-hour volume and holders, and the source line (`Jupiter · read 4:14 PM`). A figure the venue did not give is a dash, never zero, and a token with no flag raised shows no chip, never a mark that says it is safe. `FinEntry` draws it when `resultCards` includes `solana`. | Prop | Type | Description | | --- | --- | --- | | `token` | `SolanaTokenDetail` | The token, from `toolBlock` (`kind: "solanaToken"`). | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, risk?, figures?, source? }` | Classes for its parts. | Parts: `solana-token-card-header` (the price and its move), `solana-token-card-risk` (only when there is a warning), `solana-token-card-figures`, `solana-token-card-source`. ### `SolanaHoldingsCard` The agent's Solana account as a `solana_account` read found it, as `WalletCard` draws the agent wallet: what it is worth (with `2 not valued` beneath when some holdings have no price, which the total leaves out), when it was read, a table of its SOL and each token with the Solana badge by amount (`formatAssetFigure`) and value, and an **Assets** link (`routes.assets`). A holding with no price stays listed with a dash, never zero. A token with no symbol is named by its shortened mint, and one whose symbol another holding shares shows its shortened mint too, each with a copy button. When the agent has no Solana account yet, or the read failed, the card says so in a line. The SOL links to your page for the account's SOL (`routes.asset` with `SOLANA_SOL_ID`), never SOL's market. `FinEntry` draws it when `resultCards` includes `solana`, except in the middle of a trade, where it is the agent checking the account: before an approval, a question or a Solana trade, and beside the candidates a search found, which are the question. | Prop | Type | Description | | --- | --- | --- | | `account` | `SolanaAccountRead` | The answer, from `toolBlock` (`kind: "solanaHoldings"`): the account with its holdings, or the typed `no_account` or `unavailable` answer. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, holdings?, action? }` | Classes for its parts. | Parts: `solana-holdings-card-header` (with the total), `solana-holdings-card-holdings`, `solana-holdings-card-action` (the Assets link). ## Run outcome ### `RunProgress` A run that proposed moving money, step by step as it happened: what the agent read, the proposal waiting on the user's approval below, and each swap of an approved plan as it settles. It plans nothing ahead, and a step reads as done only once its result or settlement receipt is in. The head says the financial state and how many transfers settled, excluding reads. A partial or uncertain ending stays explicit after the model finishes. Unstarted and blocked actions stay still; the step working or waiting carries `aria-current="step"`. `runProgress(thread, key)` gives what it takes for a run with an approval and two steps or more. | Prop | Type | Description | | --- | --- | --- | | `progress` | `RunProgressView` | The run's steps, from `runProgress`. Its `request`, the run's first message, names a chat card's token by its shortened mint (`withShortMintMentions`). | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, bar?, steps? }` | Classes for its parts. | Parts: `run-progress-header` (the request, state and count), `run-progress-bar` (decorative), `run-progress-steps`. ### `RunReceipt` What a finished run moved, swap by swap, from its settlement receipts: what each spent and what it delivered, or that it was refunded or never ran. `runReceipt(thread, key)` gives it once the run ended with two swaps or more settled. It states no fee: the receipts carry none. | Prop | Type | Description | | --- | --- | --- | | `receipt` | `RunReceiptView` | The run's swaps, from `runReceipt`. | | `className` | `string` | Classes for the card. | | `classNames` | `{ header?, lines?, footer? }` | Classes for its parts. | Parts: `run-receipt-header`, `run-receipt-lines`, `run-receipt-footer`. ### `RunFooter` How a run ended, when that needs saying: "Stopped" for a run the user stopped; for a failure, why in plain words and the request id to quote. When an action may have started, it says to check the history before trying again. A run that a budget or spend limit stopped says which one (the user's day or month, a freeze, or your app's own limit) and when it resets, and never suggests trying again at once. A completed run draws nothing, unless you pass `feedback`: then a completed or failed run also carries a thumbs-up and a thumbs-down. One tap sends the feedback, and a tap on the thumb already chosen deletes it. Tapping the thumbs-down opens a panel of reasons (Incorrect, Not helpful, Too slow, Unsafe, Something else). A reason is optional: picking one sends it, and Skip closes the panel. Once Fin has saved what the user sent (the `value` you pass shows it and `busy` is off): - the panel closes, and focus moves to the thumbs-down if it was inside the panel; - "Thanks, your feedback was recorded." shows beside the thumbs for four seconds, then fades. The thanks never shows for feedback that is not saved: - a refused reason keeps the panel open with the refusal, so the user can try again; - Skip after a refused thumbs-down closes the panel with no thanks. A thumbs-down saved before (after a reload, say) shows pressed, and the panel does not open again. While a tap is being saved the controls ignore taps but keep the keyboard focus. A run the user stopped is never offered the thumbs. | Prop | Type | Description | | --- | --- | --- | | `item` | `RunItem` | The `run` item that closes a turn. Its `runId` names the run the feedback is for. | | `feedback` | `RunFooterFeedback` | Lets the user send feedback on the reply. Without it, no thumbs are drawn. | | `className` | `string` | Classes for the root. | | `classNames` | `{ feedback?, reasons?, thanks? }` | Classes for its parts. | `RunFooterFeedback` is `{ value, busy?, error?, onChange, tooltip? }`: | Field | Type | Description | | --- | --- | --- | | `value` | `RunRating \| null` | The user's feedback on this reply now, as Fin returned it (the run's `feedback`); `null` while there is none. | | `busy` | `boolean` | Feedback is being saved: holds the thumbs and the reasons until it lands. | | `error` | `string \| null` | Fin's refusal of the last feedback, in words, shown beside the thumbs. | | `onChange` | `(feedback) => void` | The user sent, changed or deleted their feedback. Send `{ rating: "up" }` or `{ rating: "down", reason? }` with `runs.sendFeedback`; `null` deletes it, with `runs.deleteFeedback`. | | `tooltip` | `ControlTooltip` | Wraps each icon-only control (the thumbs, the reasons' Skip) in your own tooltip. Without it they draw as they always have. | To draw a failed run your own way, `failedRunText(item)` returns the words `RunFooter` says for it: why the reply stopped and what to do next, in the same plain sentences. Show `item.reference` beside them when it is there. Model connection, timeout, rate-limit and availability failures receive bounded server-side recovery before a failed ending is published. `model_invalid_output` means terminal structured output still failed its schema after bounded repair. Earlier actions may have completed regardless of which stage failed. A reply retry should generate an answer from retained results with `profile.tools: []` in `runs.start`, rather than repeat the original action request with tools enabled. For financial recovery, use the existing eligible-action review and fresh approval. Assistant `agent.entry` events may carry `interrupted: true`; the reducer preserves that flag even if a later attempt completes the run. Mark such a draft as interrupted while nothing follows it. `transcriptEntries` leaves it out once later words of its turn exist, so it never reaches the final answer's Copy action. A `ControlTooltip` is `(label, control) => ReactNode`: it is given a control's name (`Good reply`, `Bad reply`, `Skip`, the same as its accessible name) and the control, and returns the control inside your tooltip. Render `control` as your tooltip's trigger, passing its props and ref through, and don't add a second accessible name: the control already has one. A `RunRating` is `{ rating, reason? }`: `rating` is `up` or `down`, and `reason` (one of `wrong`, `unhelpful`, `slow`, `unsafe` or `other`) only goes with `down`. A run's `feedback` from the SDK, and the body you send, both fit it. Parts: `run-footer-feedback` (the thumbs), `run-footer-reasons` (the panel of reasons after a thumbs-down), `run-footer-thanks` (the thanks once feedback is saved: a live region, empty otherwise). ## Tokens and chains ### `TokenIcon` A token's disc: its icon, or the symbol's initials, with its network's badge when you name one. Decoration only: it never identifies the asset. | Prop | Type | Description | | --- | --- | --- | | `symbol` | `string` | The symbol; its first three characters are the fallback. | | `iconUrl` | `string \| null` | A URL or `data:` URI, as `TokenInfo.icon` gives it. `null` draws the initials. | | `size` | `16 \| 20 \| 28 \| 36 \| 40` | 40 an asset row, 36 compact, 28 inline, 20 a table row, 16 within text. | | `network` | `string \| null` | The token's chain, `assetChain(tokenId)`, badged on the disc. | | `ringClassName` | `string` | The badge ring's colour, matching the surface below. | | `className` | `string` | Classes for the root. | | `data-fin-part` | `string` | The part name for its root; `AssetIcon` passes `asset-icon`. | It carries `data-fin-ui="token-icon"`, and its badge `data-fin-ui="network-badge"`. ### `AssetIcon` A held asset's icon from the token list, with its chain's badge unless `compact`. | Prop | Type | Description | | --- | --- | --- | | `asset` | `PortfolioHolding` | A holding, as Fin's wallet read or a provider names it. | | `compact` | `boolean` | A 36px disc without the badge; otherwise 40px with it. | | `className` | `string` | Classes for the root. | ## Configuration ### `FinUIProvider` How your app links, where cards link and what tokens look like, for every block inside it. It carries no data. | Prop | Type | Description | | --- | --- | --- | | `link` | `LinkComponent` | Your router's link component. Defaults to a plain anchor. | | `routes` | `Partial` | `automation(id)`, `orders()` and `assets()`, `contacts()` for your own contacts page, `asset(asset)` for a token's page and `transaction(network, id)` for your explorer's page for one transaction. Unset routes keep near.com's paths. | | `tokens` | `TokenResolver` | What each token looks like. Defaults to `DEFAULT_TOKENS`. | | `children` | `ReactNode` | The part of your app that draws Fin's blocks. | A `LinkComponent` takes `LinkProps`: `href`, `className`, `children` and an anchor's other attributes, as Next.js's `Link` does. `DEFAULT_ROUTES` holds near.com's paths: `/agent/automations/`, `/agent/orders` and `/agent/assets`. It has no `contacts()`: the contacts are your app's, so the contacts card links only where you name your page. It has no `asset()` either. Name it, and every token Fin draws in a conversation links to your page for it: a card's token (a holding, a swap's two sides, a receipt, a price, a comparison) and a ticker in a reply. It receives an `AssetRef`, `{ symbol, tokenId }`, with `tokenId` set where the card knows which token it is, and returns your page, or `undefined` for a token you have none for, which then draws as plain text. A Solana token's `tokenId` is `solana:`. The link keeps the token's look, with no colour of its own, and underlines on hover and keyboard focus; its accessible name says the token, then "open its page". Its part is `asset-link`. The user's own messages are yours to draw, so nothing in them links. Unset, the blocks draw exactly as before. `transaction(network, id)` is your explorer's page for one transaction, which a Solana receipt links each of its transactions to (`network` is `solana`, `id` the signature). A block never hard-codes an explorer, so there is no default: unset, the receipt shows each signature shortened with a button that copies it whole. ```tsx title="fin-chat.tsx" import { FinUIProvider } from "@nearai/financial-agents-react"; import type { ReactNode } from "react"; /** The tickers your app has a market page for. */ const MARKETS = new Set(["NEAR", "BTC", "ETH", "USDC"]); export function FinChat({ children }: { children: ReactNode }) { return ( (MARKETS.has(symbol) ? `/markets/${symbol}` : undefined) }} > {children} ); } ``` ### `useFinUI()` The nearest provider's `FinUIConfig`, `{ tokens, link, routes }`, with defaults where there is no provider. Use it so your own markup links the way Fin's blocks do. ### `configureFinUI(configuration)` Sets the tokens and routes the view models read outside React, such as on a server. `FinUIProvider` calls it for you; `tokens()` and `routes()` return what is set. ### `DEFAULT_TOKENS`, `RENDERED_CARDS` `DEFAULT_TOKENS` is near.com's token list as a `TokenResolver`; see [Tokens and chains](/tokens-and-chains). `RENDERED_CARDS` names the result cards, for `context.renders`. ## Types | Kind | Types | | --- | --- | | Props | `ActivityGroupProps`, `ApprovalCardProps`, `AssetIconProps`, `AutomationCardProps`, `ComparisonCardProps`, `ContactsCardProps`, `ContractTermsProps`, `FinEntryProps`, `FinUIProviderProps`, `HoldingsCardProps`, `MemecoinsCardProps`, `MessageMarkdownProps`, `NextStepsProps`, `OrdersCardProps`, `PendingApprovalChipProps`, `PerpsFiringCardProps`, `PredictionMarketCardProps`, `PredictionPreviewCardProps`, `PredictionsCardProps`, `PriceCardProps`, `QuestionCardProps`, `RunFooterProps`, `RunProgressProps`, `RunReceiptProps`, `SettlementReceiptProps`, `SolanaHoldingsCardProps`, `SolanaReceiptProps`, `SolanaTokenCardProps`, `TokenCandidatesCardProps`, `TokenIconProps`, `ToolCallCardProps`, `VaultsCardProps`, `WalletCardProps` | | Part names | `ApprovalCardPart`, `AutomationCardPart`, `ComparisonCardPart`, `ContactsCardPart`, `HoldingsCardPart`, `MemecoinsCardPart`, `MessageMarkdownPart`, `OrdersCardPart`, `PerpsFiringCardPart`, `PredictionMarketCardPart`, `PredictionPreviewCardPart`, `PredictionsCardPart`, `PriceCardPart`, `QuestionCardPart`, `RunFooterPart`, `RunProgressPart`, `RunReceiptPart`, `SettlementReceiptPart`, `SolanaHoldingsCardPart`, `SolanaReceiptPart`, `SolanaTokenCardPart`, `TokenCandidatesCardPart`, `ToolCallCardPart`, `VaultsCardPart`, `WalletCardPart`, and `PartClassNames` for a `classNames` prop | | Variants and loaders | `QuestionCardVariant`, `OptInResultCard`, `PriceRange`, `PriceHistoryLoader`, `SolanaTokenLoader` | | Handlers and data | `ApprovalHandlers`, `QuestionHandlers`, `FeedbackHandlers`, `RunFooterFeedback`, `RunRating`, `ControlTooltip`, `RuleConflict`, `AgentHolding`, `PendingApproval`, `RunItem`, `ToolItem` | | Grids | `GridBandProps`, `GridCardProps`, `GridBandPart`, `GridCardPart`, `GridHandlers`, `GridAction` | | Configuration | `FinUIConfig`, `FinRoutes`, `AssetRef`, `LinkComponent`, `LinkProps`, `TokenInfo`, `TokenResolver` | The data the props take (`ThreadState`, `TranscriptEntry`, `ApprovalView`, `ExecutionView`, `ActivityStep`, `ReplyContext`, `AutomationReceipt`, `WalletReading`, `LimitOrderView`, `ContactsLookup`, `PriceHistory`, `MarketComparison`, `PricePoint`, `EarnVaults`, `PredictionSearch`, `PredictionMarketDetail`, `PredictionPreview`, `SolanaTokenSearch`, `SolanaTokenList`, `SolanaTokenDetail`, `SolanaAccountRead`, `RunProgressView`, `RunReceiptView`, `SolanaReceiptView`, `PortfolioHolding`, `PricedHolding`, `TermRow`, `GridBandCell`) comes from [`@nearai/financial-agents-react/model`](/react-model); Fin's resources (`Approval`, `Automation`, `Grid`, `Question`, `EventPayload`) from [`@nearai/financial-agents-sdk`](/sdk-reference#types). --- # Theming Fin's blocks look like near.com until you restyle them. Four levels restyle them, from a few variables to entirely your own markup. Use the lightest that does what you need; they combine. | Level | You change | Use it for | | --- | --- | --- | | [Variables](#1-variables) | `--fin-*` custom properties | Palette, typeface, corners and density, everywhere at once | | [Classes](#2-classes) | `className` and `classNames` | One block, or one of its parts, in one place | | [Attributes](#3-attributes) | CSS on `data-fin-part` and `data-fin-ui` | A part or a primitive (every button, badge, notice) in every block | | [Your own markup](#4-your-own-markup) | The view models in `@nearai/financial-agents-react/model` | A block drawn entirely by your components | ## How the stylesheet stays out of your way `@nearai/financial-agents-react/styles.css` styles nothing outside Fin's blocks: - **Every element rule sits in the `fin` cascade layer**, so your unlayered CSS always wins. - **Every class is prefixed `fin:` and every variable `--fin-`**, so nothing collides with your classes or theme, Tailwind's included. - **Its small reset applies only to Fin's elements.** Pages without Tailwind render the blocks correctly; pages with it see no change. - **What any Tailwind 4 build shares sits outside the layer**: the `--tw-*` and `--twsa-*` properties registered with `@property`, and the `spin`, `ping`, `pulse` and `enter` keyframes. Rename your own keyframes if they use those names. In a Tailwind app, declare the layer order once, above your Tailwind import: ```css title="app/globals.css" @layer theme, base, fin, components, utilities; @import "tailwindcss"; ``` ## 1. Variables Set `--fin-*` variables on `:root`, or on any element above Fin's blocks. This makes them look like another product: an indigo accent, warm greys, a serif face, square corners and a denser rhythm. ```css title="fin-theme.css" :root { --fin-font-sans: Georgia, "Times New Roman", serif; --fin-color-green-500: oklch(0.831 0.12 277); --fin-color-green-600: oklch(0.711 0.16 277); --fin-color-green-700: oklch(0.5935 0.2 277); --fin-color-gray-500: oklch(0.556 0.011 70); --fin-color-gray-900: oklch(0.205 0.006 70); --fin-radius-md: 0px; --fin-radius-lg: 0px; --fin-radius-xl: 0px; --fin-spacing: 0.2rem; } ``` > [!TIP] > Keep each step's lightness when you change a scale's hue, so text keeps its contrast. The > `Themes/Alternate` story sets a whole scale this way. > [!NOTE] > On a phone, an approval's terms open in a sheet at the end of `body`. Set variables on `:root` > so they reach it. | Variables | Steps | Drives | | --- | --- | --- | | `--fin-color-green-` | 50, 100, 200 … 900, 950 | The accent: primary buttons, success, rising figures, the agent's mark | | `--fin-color-red-` | 50, 100, 200 … 900, 950 | Danger and falling figures | | `--fin-color-yellow-` | 50, 100, 200 … 900, 950 | Caution: pending approvals and holds | | `--fin-color-gray-` | 10, 25, 50, 100, 150, 200, 300 … 800, 850, 875, 900, 950 | Surfaces, borders and ink | | `--fin-color-blue-` | 300, 500, 700 | Information | | `--fin-color-white` | | Text on a filled accent | | `--fin-font-sans`, `--fin-font-mono` | | Typefaces. Fin loads no fonts of its own | | `--fin-font-weight-` | normal, medium, semibold, bold | Weights | | `--fin-text-`, `--fin-text---line-height` | xs, sm, base, lg, xl, 2xl, 3xl, 4xl | The type scale | | `--fin-leading-`, `--fin-tracking-` | tight, snug, normal; tight, wide | Line height and letter spacing | | `--fin-radius-` | sm, md, lg, xl, 2xl, 3xl | Corners | | `--fin-spacing` | | The base of every padding, margin and gap | | `--fin-container-` | sm, md, lg, xl, 3xl, 4xl | The widths some cards stop growing at | | `--fin-ease-` | out, in-out | Easing curves | | `--fin-default-transition-` | duration, timing-function | The default transition | | `--fin-animate-` | spin, pulse, ping | Spinners and live dots | ### Dark mode Blocks draw dark inside an element with the `dark` class (near.com's and `next-themes`' class strategy), or inside `data-fin-theme="dark"`. `.not-dark` or `data-fin-theme="light"` keeps a subtree light. Scope variables to one theme: ```css .dark, [data-fin-theme="dark"] { --fin-color-gray-900: oklch(0.96 0.004 70); } ``` ## 2. Classes Every block takes `className` for its root. A block with named parts also takes `classNames`, one class per part: ```tsx title="branded-approval.tsx" import { ApprovalCard, type ApprovalCardProps } from "@nearai/financial-agents-react"; export function BrandedApproval(props: ApprovalCardProps) { return ( ); } ``` Your classes come after Fin's and your CSS sits outside its layer, so yours win. Each block's parts are in the [components reference](/react-components). ## 3. Attributes Two attributes are the stable hooks for CSS that reaches into a block. Fin's own class names are not: they can change in any release. ### `data-fin-part` Names every block and part: `approval-card` on an approval card, `approval-card-evidence` on its exact terms. Target a part everywhere it appears: ```css [data-fin-part="approval-card-evidence"] { display: none; } ``` | Root `data-fin-part` | Block | | --- | --- | | `activity-group` | `ActivityGroup` | | `approval-card` | `ApprovalCard`. Inside: `decision-countdown`, the time left to decide; `execution-swaps`, a multi-swap execution's swaps; `grid-band`, a grid approval's band | | `asset-icon` | `AssetIcon` | | `asset-link` | A token in a card or a ticker in a reply, linked to your page for it by `routes.asset` | | `automation-card` | `AutomationCard` | | `comparison-card` | `ComparisonCard`. Inside: `sparkline`, each asset's trend line | | `contacts-card` | `ContactsCard` | | `contract-terms` | `ContractTerms` | | `memecoins-card` | `MemecoinsCard` | | `grid-band` | `GridBand`, also inside a grid's `ApprovalCard` and `GridCard` | | `grid-card` | `GridCard` | | `message-markdown` | `MessageMarkdown`. Inside: `sparkline`, a bolded asset's trend line | | `mint-address` | A Solana token's address, shortened, with its copy button, where a Solana card shows one to tell look-alikes apart: in `TokenCandidatesCard`, `MemecoinsCard`, `SolanaTokenCard` and `SolanaHoldingsCard` | | `next-steps` | `NextSteps` | | `orders-card` | `OrdersCard` | | `perps-firing-card` | `PerpsFiringCard` | | `holdings-card` | `HoldingsCard` | | `pending-approval-chip` | `PendingApprovalChip` | | `prediction-market-card` | `PredictionMarketCard` | | `prediction-preview-card` | `PredictionPreviewCard` | | `predictions-card` | `PredictionsCard` | | `price-card` | `PriceCard` | | `question-card` | `QuestionCard` | | `run-footer` | `RunFooter` | | `run-progress` | `RunProgress` | | `run-receipt` | `RunReceipt` | | `settlement-receipt` | `SettlementReceipt` | | `solana-holdings-card` | `SolanaHoldingsCard` | | `solana-receipt` | `SolanaReceipt` | | `solana-token-card` | `SolanaTokenCard` | | `token-candidates-card` | `TokenCandidatesCard` | | `tool-call-card` | `ToolCallCard` | | `vaults-card` | `VaultsCard` | | `wallet-card` | `WalletCard` | ### `data-fin-ui` Names every primitive a block draws with: each button, badge, notice and line of text. Where it applies, a primitive also carries `data-fin-variant`, `data-fin-size`, `data-fin-tone` and `data-fin-state`, so one rule restyles it in every block: ```css [data-fin-ui="button"] { border-radius: 9999px; } [data-fin-ui="button"][data-fin-variant="primary"] { background: #312e81; color: #ffffff; } [data-fin-ui="badge"] { border-radius: 2px; letter-spacing: 0.06em; text-transform: uppercase; } ``` | `data-fin-ui` | Is | Carries | | --- | --- | --- | | `button` | A button | `variant`: primary, accent, secondary, outline, dark, light, transparent, destructive, destructive-soft, success-soft; `size`: xs, sm, md, lg, xl | | `icon-button` | An icon-only button, such as a notice's dismiss or a reply's thumbs | `variant`, `size` | | `badge` | A status label | `tone`: neutral, accent, caution, danger, info; `variant`: outline, soft, solid; `size`: sm, md | | `notice` | A message under a card, such as a refusal | `tone`: info, accent, caution, danger | | `text` | A line of text | `variant`: display, title, heading, subheading, body, body-sm, label, caption, mono, muted; `tone`: default, soft, muted, faint, accent, caution, danger | | `prose` | A reply's text | `size`: sm, md | | `stream-caret` | The caret after live text | | | `card` | A panel | `tone`: raised, flat, inset, caution, danger, accent | | `disclosure` | A section that opens in place | `size`: sm, md | | `dialog` | A dialog | `variant`: modal, drawer, page, sheet; `size`: sm, md, lg; `tone`: neutral, danger | | `spinner` | Work in progress | `size`: xs, sm, md | | `kbd` | A key cap, such as a question card's number keys | | | `segmented-control` | A radio group drawn as one control, such as a price card's range tabs | `size`: sm, md | | `tool-indicator` | A tool call's status glyph | `state`: running, completed, failed, denied, invalid_input, pending_approval, pending_input, pending_confirmation, refunded, partial, not_executed | | `json-view` | An exact input or result, as JSON | | | `token-icon` | A token's disc | | | `network-badge` | A token's network badge | | The `Themes/Parts` stories show both attributes at work. ## 4. Your own markup `@nearai/financial-agents-react/model` holds the logic behind every block, so your components can draw Fin's data with none of its markup or styles. `approvalContent` reads an approval as the card does: ```tsx title="plain-approval.tsx" import { type ApprovalView, approvalContent } from "@nearai/financial-agents-react/model"; export function PlainApproval(props: { approval: ApprovalView; onDecide: (ok: boolean) => void }) { const content = approvalContent(props.approval); return (

{content.headline}

{content.terms.map((term) => (
{term.label}
{term.value}
))}
{content.readable ? null :

Update the app to review this request.

} {content.readable ? ( ) : null}
); } ``` > [!IMPORTANT] > Whatever draws an approval must show the terms Fin derived, and offer only Cancel for one it > cannot read: nobody approves terms they were not shown. The [view models](/react-model) cover the thread, replies, activity, automations, amounts and tokens the same way. --- # View models `@nearai/financial-agents-react/model` is the logic behind Fin's blocks, without the blocks: the thread fold, what an approval asks, how an automation reads, exact amounts and token metadata. Use it to draw Fin's data with your own components, to word your own surfaces as Fin's blocks do, or to read Fin's data on a server. ```ts import { threadReducer, transcriptEntries } from "@nearai/financial-agents-react/model"; ``` Every function is pure over the data Fin sends: nothing renders, fetches or keeps state. Unlike the components' client entry, it runs anywhere, a server included. > [!NOTE] > Functions that read token metadata or routes read what `FinUIProvider` configured. Without a > provider, as on a server, set them with `configureFinUI`. Unset, they are near.com's. ## Configuration | Export | Description | | --- | --- | | `configureFinUI({ tokens?, routes? })` | Sets the tokens and routes these functions read outside React. `FinUIProvider` calls it for you. | | `tokens()`, `routes()` | The resolver and routes set now. | | `DEFAULT_TOKENS` | near.com's token list as a `TokenResolver`. See [Tokens and chains](/tokens-and-chains). | | `DEFAULT_ROUTES` | near.com's paths for the agent's pages. | | `TokenResolver`, `TokenInfo`, `FinRoutes` | Their types. | ## The thread A conversation is a fold over its events. Fold the SDK's `FinStreamEvent`s as they arrive, then read the thread with these helpers. | Export | Description | | --- | --- | | `threadReducer(thread, event)` | Folds one event in. Ignores one it has seen, by `seq`, so a replay is harmless. | | `initialThread` | The empty thread. | | `ThreadState` | The folded thread: `items` in order; `approvals`, `questions` and `executions` by id; `runStatus`; live `streamingText`; the last `seq`. | | `ThreadItem` | One of `items`: a `user` or `assistant` message, a `tool` call, a `settlement`, a `question`, an `approval` or a `run` ending, which carries the `runId` it ended: what feedback on the reply is sent for. A `user` message the user sent the working run (`run.steered`) carries `steered: true` and sits where the agent read it; one an automation's run opened carries that `automation` (`{ automationId, name }`). | | `ToolItem` | A `tool` item: its name, input, phase and outcome, and, in an automation's run, that `automation` with the run's `runId`. A call the agent asked for with others carries their `batch`: its `index`, their `size` and the `group` they share, the first call's `key`. A call whose result came after its run ended carries `leftOpen: true`: the run ended before the call did, so one cut short by the person's Stop can read as stopped rather than failed. A perps order, cancellation, margin change or withdrawal whose result was unconfirmed takes its `perps.reconciled` answer as its outcome, and a Solana buy, sale or withdrawal its `solana.reconciled` answer. A Polymarket funding or order takes the latest `prediction.funding` or `prediction.order` observation instead. All are marked `reconciled: true`; for Polymarket this means an updated observation, **not** verified pUSD settlement or a settled trade. | | `StreamEvent` | An event the reducer takes: the SDK's, or the JSON your relay sent. | | `ApprovalView` | An approval, with its contract and status. | | `ExecutionView`, `ExecutionLeg` | A financial execution as the journal reported it, and one of its swaps. | | `SolanaSaleProgress` | One coin's latest swap snapshot in a sale of several Solana coins (`solana_sell_many`), with `at`, when it arrived: `ExecutionView.solanaSales` keeps one per coin, by the coin's place in the sale (`sale`), so a reader knows which coins sold and which is on its way while the sale runs. | | `RunStatus` | `idle`, `running`, `paused`, `completed`, `failed` or `aborted`. | | `isStreaming(thread)` | Whether reply text is arriving now. | | `isThinking(thread)` | Whether the agent is working with nothing streamed and no tool running. | | `runningTool(thread)` | The tool call running now, if any; never a `show_cards` call, which shows cards rather than does work. | | `streamingKey(thread)` | A stable React key for live text, kept once it is saved. | | `pendingApprovals(thread)` | The approvals waiting for the user. | | `pendingTrades(thread)` | The trades waiting on the user's decision, by coin: a `ReadonlyMap` from a Solana mint or an Intents token id to `{ side, approvalId }`, read from each pending approval's request: a `solana_buy` buys its mint, a `solana_sell` and each sale of a `solana_sell_many` sell theirs, and each swap of an `intents_execute` request sells what it pays with and buys what it produces. A send, a withdrawal, an order or a rule trades nothing. When two waiting approvals name one coin, the later in the thread says its side. A card's buttons never contradict one: offer no Buy of a coin whose sale waits and no Sell of one whose buy waits; say where the decision is instead. | | `pausedApprovalExpired(thread)` | Whether the run waits on an approval that expired. | | `toolForApproval(thread, approval)` | The tool call an approval belongs to. | | `approvalForTool(thread, item)` | The approval a tool call waits on or was decided by. | | `executionForApproval(thread, approval)` | The execution an approved trade produced. For a Solana buy or funding it is the 1Click leg that moves USDC into the Solana account, which says whether the SOL has arrived. | | `executionForTool(thread, item)` | The execution a trade's call drove, for `ToolCallCard`'s `execution`. | | `runOfItem(thread, key)` | The run that drew an item, or `null` when the journal cannot identify it. Pass it with a result card's message so the host steers only into that same run while it waits on its question. | | `runEndedAfter(thread, item)` | Whether the run ended after this call, so it will never finish. | Independent reads can finish out of `batch.index` order. Feed events to `threadReducer` in durable `seq` order; it matches results by call identity. Use each item's batch index for the original display order, and keep completed results when a sibling fails or the user stops the run. `composite.progress` is folded, not dropped: `executionForApproval` and `executionForTool` return one parent at `executions["composite:" + callId]` for `composite_execute`. Its `compositeProgress` holds the latest revision's numbered pieces, each with its tool, nullable `operationId`, `todo` / `live` / `done` / `bad` / `skip` state and optional failure reason. Older or duplicate snapshot revisions cannot overwrite it. A piece with an operation id also has its own `ExecutionView` under that id, with `compositePiece: { parentKey, index }`; its Intents swaps and receipts stay on that operation, never on an arbitrary sibling sharing the approval. The conversation keeps one tool call and one approval, not a new card per piece. Later perps or prediction observations are kept as the piece operation's `reconciledOutcome`, not substituted for the parent call's whole result. A late piece observation never completes its sibling pieces or creates a second approval. Progress is display evidence, not consent or a result: only the exact composite contract and its frozen piece inputs define the signature. The final `composite_execute` tool outcome holds each piece's result and unused venue balances; a completed call does not mean every piece bought. A venue in `unusedUnavailable` means its final balance could not be read, not that it is zero. Offer an account review and withdrawal instead of claiming no venue money remains. ## The transcript | Export | Description | | --- | --- | | `transcriptEntries(thread)` | What a transcript draws, in order. Consecutive read calls fold into one `activity` entry with their cards. Intents and Solana money calls retain their own financial entry even without a per-call approval. A turn says each thing once: an interrupted draft is left out once later words of its turn exist, and a long reply is left out when a later one says it again with only reads between them. The thread keeps both. | | `TranscriptEntry` | `{ kind: "item", item }` or `{ kind: "activity", key, items, blocks }`. | | `entryKey(entry)` | A stable React key. | | `threadTurns(thread)` | The thread as turns, for an app that sends `show` or `placement` in `context.renders`. Each `Turn` holds its `answer` (the agent's words split at the cards it placed, then approvals, questions, trades, receipts, saved rules and asks for a deposit where they happened), its `work` (every other call, in order: its steps), the `blocks` its reads draw (a turn that saved an automation leaves out its prediction-market reads' cards: they were how the agent found the market to watch), `placed` (whether the agent chose cards for the turn: its replies name any of its cards, or it called `show_cards`), `legacy` (the turn opened before cards were placed, on 2026-10-25 at 17:00 UTC, by when its opening message or, with none, its first step happened; a turn whose events carry no time is not) and `ended` (its run's ending). A name for a call the answer already draws (an approval's, a question's, a trade's, a saved rule's or a deposit ask's) places nothing more. A `show_cards` call is never one of a turn's steps: the cards its result accepted stand in the answer at the call, after the words written before it, and it can name a read of an earlier turn. Words still streaming are the last turn's last parts, so a card shows as soon as its line is whole. A read draws a card only where the agent placed it: draw `blocks` after the words of a `legacy` turn that placed none, and leave the reads of any other turn in its steps. | | `Turn`, `TurnPart` | A turn, and one part of its answer: `{ kind: "words", key, text, item? }`, `{ kind: "card", key, name, tool, focus? }`, `{ kind: "cards", key, tools, focus? }`, or `{ kind: "item", key, item }`. A `cards` part is several reads of one kind that one `show_cards` call named together: draw Solana tokens as one list, and any other kind one card after another. `focus` is what the call said matters inside the cards: token ids, mints or symbols. | | `MAX_PLACED_CARDS` | The most cards a turn places (3), by card lines and `show_cards` calls together; a name past them draws nothing. | ## Replies | Export | Description | | --- | --- | | `splitReplyNextSteps(text)` | A reply's `body`, apart from the `nextSteps` it suggests and the `shareLines` it wrote for an app that shares answers (`context.renders` with `share`). | | `ReplyParts` | `{ body, nextSteps, shareLines }`. | | `splitReplyCards(text)` | A reply in order: its words and the cards it places (`[card r7k2q]` lines, or several side by side on one line, each placed in order), as `ReplyPiece[]`. A card line inside a fenced block is text; the start of a card still streaming is left out. | | `ReplyPiece` | `{ kind: "text", text }` or `{ kind: "card", name }`. | | `replyCardName(callId)` | The name a read's card goes by, from its call id alone, exactly as the host gives it to the agent. | | `withoutReplyCards(text)` | A reply's words with every card line left out, for an app that draws no cards. | | `replyContext(thread.items)` | Each asset replies name, with its icon and trend line, by symbol. When the thread's reads gave one ticker to several coins (Dogecoin and Binance-Peg Dogecoin are both `doge`), it is the one your token list's `marketId` names, if the thread read it; otherwise the latest read's. | | `ReplyContext`, `ReplyAsset` | What it returns, and one asset of it, with its `tokenId` where the thread or the token list gives one. `ReplyContext.ticker(word)` is the asset a word of the reply's own text names, spelled exactly as the thread or the token list spells it. | | `rehypeReplyFigures`, `rehypeReplyTables`, `rehypeReplyCitations`, `rehypeReplyTickers` | The rehype passes behind colours, panels, source chips and linked tickers, for your own Markdown renderer. Changes are wrapped in `span[data-change="up\|down\|flat"]`, and each word that could be a ticker, outside code and links, in `span[data-ticker]`. | | `signedFigures(text)` | Where each signed change sits in text, and which way it moved. | | `Direction` | `up`, `down` or `flat`. | | `linkSource(href)` | A link's host, and the data provider behind it if Fin knows it. | | `providerReportedAs(id)` | The data provider a tool result names, with its logo. | | `SourceProvider` | `{ id, name, logo? }`. | ## Activity | Export | Description | | --- | --- | | `activityStep(item, ended)` | One tool call in words, with its source and time: `activityStep(item, runEndedAfter(thread, item))`. | | `activitySummary(steps)` | The line that sums the steps up. | | `ActivityStep` | One step. | ## Result cards | Export | Description | | --- | --- | | `toolBlock(item)` | What a completed call's result draws: an `automation`, the `wallet`, `orders`, `contacts`, a `price` (a `market_history` read of one asset) or a `comparison` (of several), `vaults` (an `earn_vaults` read), `predictions` (a `prediction_markets` search), a `predictionMarket` (a `prediction_market` read), a `predictionPreview` (a `prediction_preview` walk), a `tokenCandidates` (a `solana_token_search`), `memecoins` (a `memecoins_top` list), a `solanaToken` (a `solana_token` read), `solanaHoldings` (a `solana_account` read), a `firing` (an automation's run placing its sealed perps order: `PerpsFiringCard`, with the `automationId` to read), a `deposit` (a `deposit_request` result: what a request lacks, for the deposit your own app draws, standing in the turn's `answer` where the call happened, never among its `blocks`; `FinEntry` draws nothing for it), or `null`. A contacts lookup that matched nobody draws nothing; one that found the user has none saved draws the empty card. A history read with no asset observed, a prediction search that found no event, a token search that found no token and a memecoin list with no row draw nothing, and so does a Solana read whose result does not parse as the `/v1` shape it must have. | | Grid tool blocks | `toolBlock(item)` also returns `grids` for the grid `grid_create`, `grid_pause`, `grid_resume` or `grid_cancel` returned, or the page an `intents_grids` read returned. A grid read that found none draws nothing. | | `ToolBlock` | Its result, with the typed data each card takes. | | `AutomationReceipt`, `WalletReading`, `LimitOrderView`, `ContactsLookup`, `GridOutput` | What `AutomationCard`, `WalletCard`, `OrdersCard`, `ContactsCard` and `GridCard` take. A `WalletReading` row carries an optional `priceStatus` (`HoldingPriceStatus`); one this version does not know reads as absent. | | `EarnVaults`, `EarnVault` | What `VaultsCard` takes from an `earn_vaults` read (`kind: "vaults"`): each tradable vault's name, provider, chain, share token, payment asset, minimum, fees and share price as the read gave them, its provider's current `rate` (`{ percent, type, source, observedAt }`, or `null` when none could be read, or the read predates rates), and how many vaults are unlisted. | | `runProgress(thread, key)`, `RunProgressView`, `RunProgressStep` | The steps of the run an item belongs to, as they happened, for `RunProgress`: `null` unless the run opened an approval and took two steps or more. Its `request` is the run's first message as the user reads it back, a chat card's `mint
` shortened. | | `firstApprovalOfRun(thread, key)` | Whether an approval is the first its run opened, where `FinEntry` draws the progress. | | `runReceipt(thread, key)`, `RunReceiptView`, `RunReceiptLine`, `ReceiptAmount` | What the run an item belongs to moved, from its settlement receipts, for `RunReceipt`: `null` until it ended with two swaps or more settled. | | `PriceHistory`, `MarketComparison`, `PricePoint` | What `PriceCard` and `ComparisonCard` take: each asset's figures as the tool's own decimal strings, its ticker from the reviewed market catalog, and the line to draw (`points`: the daily `series` when the read asked for it, dated; else the trend, undated). A `PricePoint` is `{ at, priceUsdDecimal }`; a loader's points carry `at` as an ISO date-time. | | `PredictionSearch`, `PredictionEvent`, `PredictionMarketLine` | What `PredictionsCard` takes from a `prediction_markets` search (`kind: "predictions"`): its `status` (`open`, or `settled` when the call asked for closed events), when it was read, the query, and each event with its title, venue `url`, end date, volume, liquidity, how many markets were left out and the markets shown. A market carries its `marketSlug`, question, short label, two outcomes with their prices, its spread and `weakQuote`, and for a settled market `resolvedOutcome` and `closedAt`. Every figure is the tool's decimal string. | | `PredictionMarketDetail` | What `PredictionMarketCard` takes from a `prediction_market` read (`kind: "predictionMarket"`): the question, venue `url`, end date, `open` (trading), `closed` (the venue closed it; a market that is neither is inactive) and `acceptingOrders`, two outcomes with their prices (`null` when unpriced), volume, liquidity, the venue's cleaned `rules`, the resolution source's host, `resolvedOutcome` and `closedAt` for a closed market, and `readAt`. | | `PredictionPreview` | What `PredictionPreviewCard` takes from a `prediction_preview` walk (`kind: "predictionPreview"`): the market, question and outcome, `depth` (`budget_spent`, `book_too_thin`, `below_minimum` or `no_asks`), the stake, shares, cost, unspent amount, average, best and worst price, levels used, the venue's minimum, when the book last changed (`bookUpdatedAt`) and `readAt`. Fees are not included and it is never a quote. | | `PredictionBlock` | The three prediction-market variants of `ToolBlock`. | | `SolanaTokenSearch`, `SolanaTokenList`, `SolanaTokenDetail`, `SolanaAccountRead`, `SolanaBlock` | What the Solana cards take, exactly the `/v1` shapes the tools return: a search with its candidates (`kind: "tokenCandidates"`), a ranked list in one lane and window (`"memecoins"`), one token with its stats and `risk` (`"solanaToken"`, with the `view` its read asked for: `price` by default, `safety` or `trading`, so a card can open on what the person asked about), and the agent's Solana account (`"solanaHoldings"`), which is either the account with its holdings or the typed answer that it has `no_account` or that it is `unavailable`. `SolanaBlock` is the four variants of `ToolBlock`. Every figure is the tool's own decimal string, and a token is named by its mint. | | `SOLANA_RISK_COPY`, `riskFlagViews(risk)`, `worstRiskFlag(risk)` | Every risk flag Fin raises in plain words, a `label` and the `line` that says what it means for whoever holds the token (`The creator can freeze your tokens, so you might not be able to sell them`). `SOLANA_RISK_COPY` has an entry for each flag Fin can raise, so a flag with no words fails typecheck. `riskFlagViews` lists the raised flags with their words, the ones that refuse a buy first and the soft ones by how much they matter, and `worstRiskFlag` is the first. `RiskFlagView` is one of them and `RiskFlagCopy` its words. | | `riskLevelView(level)`, `RiskLevelView` | A token's overall verdict as a `label` and a `tone` (`neutral`, `caution` or `danger`): `No flags raised`, `Medium risk`, `High risk`, `Can't be bought` or `Unknown risk`. There is no tone for safe: the checks look at a token's setup and its market data, which cannot promise it is. | | `riskWarnings(risk)`, `RiskWarning` | The warnings a token wears as chips, worst first: `Unknown risk` when Fin could not read its setup, then each flag raised, the ones that refuse a buy first, each a `label` and a `tone` (`danger` refuses a buy, `caution` is a warning to read). None for a token with no flag raised, which the Solana cards and the fin app draw with no chip at all. | | `searchContenders(search)` | A search's candidates as `TokenCandidatesCard` offers them: `contenders`, the ones that share the name or symbol asked about (or, when the search is ambiguous, the top match's symbol), those Fin would buy before those it wouldn't (`tradable`), verified first and then by liquidity, deepest first; `others`, the rest in the search's own order, which wait behind Show more; and `shared`, a symbol two contenders or more carry, which the card asks about (`Which WIF?`), or `null`. A search none of whose candidates bears the words asked offers its best match first. | | `solanaRisks(thread.items)` | What a chat's Solana reads found of each token's risk, by mint, the latest read of a token winning: the `tokenRisks` an approval card takes so a Solana ticket wears its token's worst warning. It parses every Solana read in the thread, so keep its answer for as long as `thread.items` is the same list; `FinEntry` does. | | `withShortMintMentions(text)` | A message as the user reads it back: each `mint
` a chat card wrote (`Use BONK, mint DezX…B263`) shortened as every mint is shown, for your own bubble, queue and title. Any other address stays whole, and the message sent keeps the mint whole for Fin. | | `tokenAge(createdAt, observedAt)`, `organicShare(stats)`, `collidingMints(tokens)` | A token's age at the moment of the read, never by the reader's clock, as `12m`, `5h`, `3d`, `4mo` or `2y`, and `null` when the venue gave no creation time; the share of a window's volume the venue judges organic, as a whole percent worked from the exact figures (`63%`), and `null` when it cannot say; and the mints in a list whose symbol another token shares, which a card shows shortened so look-alikes can be told apart. | | `automationIdsOf(thread.items)` | Every automation the thread created, edited or archived, to read each as it is now. | | `gridIdsOf(thread.items)` | Every grid the thread created, changed or read, to read each as it is now for `FinEntry`'s `grids.current`. | | `RENDERED_CARDS` | The cards Fin's blocks draw, for `context.renders`: `receipts`, `automations`, `balances`, `orders`, `contacts` and `grids`. | `AutomationReceipt` accepts retained creation receipts and revision-bound edit receipts (`edited` or retry `existing`). `toolBlock` renders completed edits from their persisted `tool.result`, keyed by call identity; durable replay restores the same receipt, not a client-reconstructed edit. Refresh your shared owner read on each committed edit revision. `AutomationCard` ignores an older cached definition while that read catches up, so chat and the automation page converge on the same revision. An `automations_archive` result folds through the ordinary `tool.result` replay path and draws an `automation` block. Its `AutomationReceipt.status` is `archived`, with `contractRevocation` preserved as `none`, `confirmed` or `pending`. Reconnect/reload must replay stored events, not reconstruct an archive from assistant prose. Pending remote acknowledgement remains pending in the receipt; never infer it from a completed run. When starting a run, also send `context.country` from your server's edge geolocation with every message; see [Tokenized stocks](/concepts#tokenized-stocks) for country and purchase restrictions. ## Approvals | Export | Description | | --- | --- | | `NearIntentsContract` | A money approval's contract (`type` `near_intents_transfer`), or an automation's grant. `ContractTerms` reads it. | | `approvalContent(approval, { holdings?, now? })` | What the card shows: `headline`, `terms`, `approveLabel`, whether it is `readable`, the optional `risk` notice, and the exact frozen `edit` when this is an automation edit. Render `risk` before approval without hiding it: Polymarket funding explains that its bound covers only the first leg and final pUSD is estimated. A Solana buy, sale, funding or withdrawal reads from its exact grant: its `terms` are its figures (`You pay`, `You get`, `Max loss`, `Valid until`), then what its card keeps behind Details, the token address and its `copy` action among them, and the ticket draws all but `Valid until`, whose time its band's countdown already shows; `holdings` that price a Solana token by `solana:` add an estimate to `You get`. A missing, mismatched or multi-execution grant is not `readable`. A standing Solana grant on an `automation_create` approval reads the same way, its `headline` the rule's sentence with every price-threshold digit and its `approveLabel` `Approve automation`, when the host's contract and the stored definition agree on every term. | | `TermRow` | One row of `terms`: `label`, `value`, `mono?`, `tone?` (`caution` for the term to read first, such as a loss bound above 3%) and `copy?` (`{ text, label }`, a button beside a shortened value that copies the whole). | | `ApprovalContent` | What it returns. | | `deriveApprovalState({ approval, … })` | Where an approval stands, never past what the journal proves: pending, denied, expired, executing, settled, failed and the rest. A limit order ends `placed`, `not_placed`, `cancel_requested`, `not_canceled` or `unconfirmed`, never `executed`. A perps margin change ends `executed` labelled `Applied`, `not_executed` labelled `Not applied`, or `unconfirmed`. Polymarket delivery to the bridge stays awaiting, not settled; an unverified pUSD credit never advances it to funded. A Solana call's `label` is the step it is on (`Funding your Solana account`, `Swapping on Solana`, `Sending back to your wallet`) or how it ended (`Done`, `Partly done: SOL is in your Solana account`, `Partly done: SOL is with 1Click` for a sale or a withdrawal whose transfer to 1Click landed and whose outcome left no SOL in the account, `Partly done` with a line to check the Solana account when the outcome says neither, `Didn't run (expired)`), from the same journal and outcome the card reads. | | `deriveExecutionState(input)`, `ExecutionState`, `ExecutionStateInput` | The financial state of a tool call without a per-call approval. Pass its `tool`, `outcome`, running/ended facts and available execution evidence. Solana calls use their own outcome status, so a completed tool result remains awaiting, partial or refused until its financial evidence says otherwise. | | `deriveSolanaReceipt(approval, outcome)` | A Solana call's receipt from its own outcome; only the approval's `tool` and optional `contract` are needed, so a standing occurrence can pass `{ tool }`. It returns the receipt, or `null` without a Solana detail: `title`, `status`, `rows` (paid, received, average price, network fees, SOL left in the account, every figure exact), the transactions it signed and the follow-ups a partial ending offers. What `SolanaReceipt` takes. | | `SolanaReceiptView`, `SolanaReceiptTransaction` | What it returns, and one transaction of it: its `purpose` (`swap` or `sweep`), state and whole `signature`. | | `ApprovalState`, `ApprovalViewState` | What it returns, and the state's name. | | `SwapRow` | One frozen action's display state. A terminal blocked row can carry `failure` with its bounded cause category and, for a verified price limit, quote terms in the frozen asset's exact units. | | `executionRecoveryChoices(outcome, candidates?)` | Verified fresh-review choices from the result wrapper or a later owner-scoped status read. Claimed actions require an explicit verified `refunded` or `not_executed` candidate. A newly proven unclaimed action without a historical refusal has category `unclaimed`; it carries no invented failure cause. This is display evidence, never spending authority. | | `executionRecoveryClaimsAreTerminal(outcome, execution)` | Whether all original claims and signed journal siblings have terminal receipts. A later receipt outranks an older uncertain result; an unclaimed candidate never erases an unresolved signature. | | `contractHeadline(contract, definition?)` | The sentence naming a proposal, as the card, chip and activity row word it. | | `approvalConsent(input)`, `ApprovalConsent`, `ApprovalConsentInput` | Reads an approval once: its state, definition, contract display and the one view it has (`card`, `order`, `perps`, `prediction`, `predictionOrder`, or `solana`), its exact terms and headline. A request no view reads is `unreadable` and cannot be approved. | | `decisionEvidence(thread, approvalId, { format?, now? })` | What a pending decision is based on, for its card: `based`, the completed reads of the decision's own turn that share its subject, the latest read per subject (for a Solana buy or sale the Solana account and the coins traded, the coins of a multi-coin sale on one row; for a NEAR Intents swap, send or withdrawal the agent wallet, the contact it pays and the history of the assets it trades), each an `EvidenceRead` with the `tools` behind it to open in place, a `title`, a `detail` and its `icons`; and `after`, what the person holds once it runs, from the latest read of those holdings less what the decision spends and plus what it buys at the price its reads carried, or `null` without such a read. `null` for an approval the thread does not hold or one no longer pending. Every figure is exact decimal arithmetic; `format` takes your own number formatters so the words read as your app does. | | `DecisionEvidence`, `EvidenceRead`, `EvidenceIcon`, `AfterLine`, `EvidenceFormat`, `DecisionEvidenceOptions` | What it returns (`{ based, after }`), one row and its mark (a coin, a chain, the wallet, a person), the line (`{ lead, text }`: "After this buy" "you’ll hold about 121.35 POPCAT and have 5,309.80 USDC left."), the formatters it takes and its options. | | Grid approvals | `approvalContent` reads a grid from its signed contract; one this version cannot read is not `readable`. `deriveApprovalState` ends a grid tool `executed` with the grid's own status line (`gridStatusLine`), rather than saying a trade executed. `contractHeadline` reads `Trade ZEC in a grid, 1,100 – 1,300 USDC`. | | `standingDefinition(approval)` | The automation an `automation_create` approval would save. | | `deriveOrderView(approval)` | A limit-order approval's headline and terms, or `null`. An order that pays with a stablecoin (the token list's `type:stablecoin` tag) reads as a buy priced per the asset bought. | | `OrderView` | What it returns. | | `orderTermsView(terms)` | A placed order's terms in the card's words, for an orders screen: `side` (`buy` or `sell`), the `asset` its price is per unit of, the `price` bound in `priceAsset`, `receivesAtLeast`, `headline` and `terms`. Pass `WalletOrder.terms`. | | `OrderTermsView`, `OrderTermsSource` | What it returns, and what it reads. | | `orderStatus(order)` | Where an order stands, as `label` and `tone`: `Open`, `Partly filled`, `Cancelling`, `Filled · paying out`, `Filled`, `Cancelled`, `Expired` and the rest. Pass `WalletOrder.observation` or a `LimitOrderView`. A fill never reads done while its payout can change. | | `OrderStatus` | What it returns. | | `resolveAsset(term)` | A contract's asset with its symbol and icon, by exact id, never by symbol. | | `ResolvedAsset` | What it returns. | | `actionInputPhrase(action, asset)`, `actionOutputPhrase(action, asset)` | One action's input and output in words. | | `formatEstimateUsd(value)` | An estimate from an exact `Decimal`: `$12.35` below a thousand, `$0.004` below a cent, `$1,235` from a thousand. | | `Decimal` | An exact decimal, such as `assetUsdValue` returns. Never a JavaScript number. | | `PricedHolding` | A holding with the price it was read at. | | `VaultRate` | A curated vault's current rate, `{ assetId, rate }`, as the Earn vaults route lists it: what `ApprovalCard`'s `vaultRates` takes. | `approvalConsent` intentionally marks `composite` contracts and `composite_execute` requests unreadable, even if every piece is valid. The shared `ApprovalCard` does not draw basket terms and remains Cancel-only. An enabled product implementing its own basket card must validate the whole composite and frozen input, match every piece, and reuse each piece's existing consent view. One unknown, missing, malformed or mismatched piece means refusal-only. Never turn a shared composite into an approvable consent model without a complete packaged renderer. A cash-out's second piece, `perps_freed_withdrawal` or `prediction_freed_withdrawal`, has no shared consent view at all (`approvalConsent` reads it as unreadable): it is a withdrawal of what the exit before it freed, at most `upToRaw`, so a product's own card draws it from those exact terms and names `upToRaw` only as the most that can come back. A completed `intents_execute` outcome can carry optional `financialFailures` beside its unchanged `result`: `nodeFailures` identifies exact unclaimed actions, and historical `preflightFailure` describes a shared request check. A price-limit diagnostic states the authenticated quoted minimum or maximum against its approved bound, including fees, spread and slippage headroom; it is not realized slippage. Skipped dependencies have no invented quote failure. The metadata wrapper preserves the legacy strict financial result shape. Older React consumers continue showing that result; older tool-outcome decoders may discard the unknown optional wrapper. The updated React model validates and combines the metadata only for presentation. Fin derives it from retained dispatch steps without changing stored operation outcomes, preserving old API and rollback readers too. A recovery child's wrapper also carries `recovery`: the original operation id, the mapping from this card's action indices to original indices, and the child's currently approved loss bound. Route its next fresh review to that original operation. Root operations omit this field; `null` means no safe mapping was proved, so expose no recovery control. This routing context grants no spending authority. The backend excludes settled or uncertain family attempts and independently proves any terminal failed attempt eligible before admitting a replacement. A later original receipt can resolve a result that was uncertain when the run ended. Read the owner-scoped `remaining-actions` endpoint before offering another attempt, bind its `operationId` to the requested operation, and pass ready `candidates` through `remainingRecoveryEvidence` on `FinEntry`/`ApprovalCard`/`ToolCallCard`. Status failures expose a status-only retry. Never prepare an attempt automatically. The Fin app aborts superseded reads, rejects another account's or operation's response, and reads once per changed receipt or explicit retry without polling. Fresh unclaimed evidence may clear stale checking/quoting progress to `Not started`; actual claims, signatures and terminal receipts retain precedence. No old blocked row means no inferred cause. If drawing your own approval card, an `ApprovalContent.edit` must be rendered as the exact target `automationId`/`snapshot`, current definition, requested `changes`, complete `result` and prior used/reserved/resulting remaining allowance **before** offering approval. Its empty ordinary `terms` array is not permission to show only the headline. Offer only cancellation when `readable` is false, and retain the existing owner-signature flow whenever either definition has a financial contract. Prefer `ApprovalCard` when you do not implement that full exact presentation. ## Grids A grid is one signed contract for a range of resting limit orders that re-arm as they fill. These read it exactly: prices stay decimal strings, amounts atomic units, and every figure is bigint or `Decimal` arithmetic rounded once where it is shown. | Export | Description | | --- | --- | | `gridApprovalView(approval, { holdings?, now? })` | A pending `grid_create` approval as its card draws it, from the signed grid contract: `headline`, `subline` (`9 levels · 30 days`), `approveLabel`, the `base` and `quote` assets, the `band`, the `stats` (`Each cycle`, what one cycle earns at least; `Buys rest`, the quote its buys use at the start; `Each order`, each order's size), the `notes` on the card's face (what happens outside the range, and that the idle cells never place an order), `cautions` (a pinned precision the token list disagrees with), every term in `terms`, and the `footnote` (`3 orders`). `null` for any other contract and for a grid contract this version cannot read. `holdings` only places an estimated now dot. | | `GridApprovalView` | What it returns. | | `gridView(grid, { price?, now? })` | A grid read (`GridOutput`) as `GridCard` draws it: `title`, `eyebrow` (`Grid · day 6 of 30`), the compact `headline`, its `status` badge and `statusLine`, the `stats` (earned, buys and sells resting, the base it holds), the `band`, the cells with completed cycles in `fills`, the compact `summary`, the `stalled` count, and whether it `canPause`, `canResume` or `canCancel`, or is `final`. | | `GridView`, `GridStatus`, `GridFill`, `GridStat` | What it returns, its badge, one cell's completed cycles, and one figure (`label`, `value`, `detail`, `tone`). | | `GridBandView`, `GridBandCell`, `GridBandSide` | What `GridBand` takes: the `levels`, the `cells` (`{ side, resting?, cycles? }`, `side` `buy`, `sell` or `idle`), the `price` now and the `unit`. | | `gridHeadline(terms)` | The sentence naming a grid from its terms. | | `gridStatusLine(grid)` | Where a grid stands, in one sentence: `Running: its orders rest at 1Click and re-arm as they fill.` | | `GridOutput` | A grid as Get a grid and the grid tools return it: the SDK's `Grid`. | What a cycle earns at least is the sale's minimum receive (the quantity at the cell's high level, rounded down to the quote's smallest unit) less the buy's cost (the quantity at the low level, rounded up): the figure the two orders guarantee, before fees. ## Automations | Export | Description | | --- | --- | | `automationStatus(automation)` | Its status badge: label and tone, `Needs you` while `waitingForOwner` is set, `Setup needed` while an owner webhook has no key, and `Watching news` or `News checks paused` for a news exit (`rule.news`), which never needs a webhook. | | `monitoringLabel(automation, nowMs)` | The sentence beside the badge. | | `automationCheckSummary(automation)` | How often it checks. | | `automationConditionSummary(automation, catalog?, price?)` | What it waits for, with assets named. A condition that reads only Solana tokens' prices names each token by its symbol (or its shortened mint, never the whole one, whatever catalog is at hand) and states each price level in `price`'s words, `formatTokenPriceUsd` by default (`$0.0₅495`, not the 23 digits it was saved to). | | `withReadablePrices(rule, price)`, `PriceWords` | The rule as its sentence words it: each level a Solana token's price is compared with, in `price`'s words. Only the sentence reads the copy; the rule stays as saved everywhere else. | | `readableRuleSummary(rule, { utc? })` | Its schedule and limit in words. | | `firingSummary(rule)`, `deliverySummary(rule)` | What one firing does, and how it delivers. | | `conditionSummary(condition)` | A condition as an expression. | | `contractStatus(contract, nowMs)` | Its grant's state: `Active`, `Revoked`, `Expired`, `All executions used` or `Spend cap used`. | | `ContractStatusLabel` | Those labels. | | `spendCapProgress(contract)` | A capped grant's budget, such as `Budget 5 USDC (1 spent, 4 left)`; `null` without a cap. | | `perpsAutomationActionSentence(contract)` | What one firing of a `perps_automation` grant does: `Open a $200.00 BTC long at 3× cross`, `Reduce your BTC long by 50%`, `Close your ETH short` or `Add 25 USDC margin from your agent wallet`. | | `perpsAutomationExitsPhrase(contract)` | An `open` grant's native exits from the mark it opens at, such as `take-profit +10%, stop-loss −5%`; `null` without any. | | `perpsAutomationActionLine(contract)` | The same with its one bound, and an open's exits: `… · market within 1% of mark` or `… · max loss 3%`. | | `perpsAutomationLimits(contract)` | How often until when: `up to 3 times · until Sep 12`, or `once · until Sep 12`. | | `automationCanToggle(automation)` | Whether it can pause or resume. A revoked grant cannot resume. | | `Occurrence` | One firing. | | `runPlace(run, automation)` | A run's place among its automation's: `4 of 30`, or `4` past or without a limit; null for an exit. | | `automationRunCount(automation, listed?)` | How many times it has run. | | `occurrencePresentation(occurrence)` | A firing's status, in words and tone, for every `state`, a recorded ending first. | | `occurrenceSelectionLabel(selection)` | What a firing selected. | | `occurrenceThreadLabel(occurrence)` | A firing's conversation label. | | `automationTime(value, rule?)` | A time in the automation's calendar time zone. | | `durationLabel(seconds)` | A duration in words, such as `1 hour 30 minutes`. | ## Amounts and values Exact decimal arithmetic on Fin's strings, rounded once where shown, never through a JavaScript number. | Export | Description | | --- | --- | | `formatUsdCents(cents)` | `"$10.15"` from integer cents. | | `formatUsdCompact(usdDecimal)` | `"$1.2B"`, `"$34.5M"`, `"$870K"` from a decimal string: cut to one decimal place, never rounded up, so a figure never overstates; under a thousand, `"$420"` or `"$0.004"`. | | `formatTokenPriceUsd(priceUsdDecimal)` | A token's price from a decimal string: to the cent from a dollar up (`"$104.20"`), and below a dollar four significant digits (`"$0.0123"`), so a memecoin's price is not blurred to the cent. | | `formatAssetAmount(asset)` | An exact amount at the asset's scale, such as `1.999999`. | | `formatAssetSummary(asset)` | A row's amount: four decimals, cut not rounded, `< 0.0001` below. | | `formatAssetFigure(amountRaw, decimals)` | A card's amount: four significant digits, cut not rounded (`0.0000234`); grouped whole units from a thousand. | | `assetUsdValue(asset)` | A priced amount's exact dollar value; `null` without a price or scale. | | `displayAssetUsdCents(asset)` | That value in whole cents. | | `displayPortfolioUsdCents(assets)` | A wallet's total in cents, rounded once; `null` if any holding is unpriced. | | `displayPricedUsdCents(assets)` | `{ cents, unpriced }`: the total of the priced holdings in cents, rounded once, and how many have no price. Never blank. | | `priceStatusLabel(status)` | What a card says of a price that isn't a fresh close: `"Carried"`, `"Last trade"` or `"No price"`; `null` for `priced` or no status. | | `HOLDING_PRICE_STATUSES`, `HoldingPriceStatus` | How a balance read found a price: `priced`, `carried`, `last_trade`, `unpriced`. | | `holdingDisplay(asset)` | A holding with the token list's name, icon and network. | | `holdingId(asset)`, `holdingTokenId(asset)` | A holding's id, and its token when the list knows it. | | `PortfolioHolding`, `AssetAmount`, `PricedAmount` | A holding; an amount at its scale; and one with its price. | ## Tokens and chains These read the configured `TokenResolver`; [Tokens and chains](/tokens-and-chains) explains them. | Export | Description | | --- | --- | | `getTokenMetadata(tokenId)` | A token's metadata by exact id; `undefined` if the list lacks it. | | `withTokenMetadata(asset)` | An asset with the list's symbol and name; nonempty catalog artwork takes precedence, otherwise its supplied `iconUrl` is retained. Amounts are unchanged. | | `finAssetId(tokenId)` | Fin's opaque id for a token, derived as Fin does. | | `catalogTokenId(assetId)` | The token behind one of Fin's opaque ids. | | `assetChain(tokenId)` | The chain a token comes from; a `solana:` id is on `solana`. | | `solanaTokenId(mint)`, `solanaMintOf(tokenId)`, `SOLANA_TOKEN_PREFIX` | A Solana token's id, `solana:`, the mint behind such an id, and its prefix. The resolver keys Solana tokens this way. | | `shortMint(mint)` | A mint shortened the way a grant's headline shortens it: its first four and last four characters, `DezX…B263`. | | `solanaTokenIcon(mint)` | A Solana token's icon as your resolver names it by `solana:`, or `null`, which draws the mint's monogram. A read's `iconUrl` is a path of Fin's API that a browser reaches only through your server, so your resolver names your server's address for it. | | `SOLANA_SOL_ID` | `solana:sol`, the SOL the agent's own Solana account holds, as `SolanaHoldingsCard` names it to `routes.asset`: no mint, so `solanaMintOf` answers `undefined` for it. | | `assetNetwork(tokenId)` | That chain's display name. | | `tokenNetworkName(chain)` | A chain's display name. | | `networkIcon(chain)` | A chain's badge for light and dark, or `null`. | ## Fixtures `@nearai/financial-agents-react/fixtures` holds realistic Fin data, to draw every state of Fin's blocks in your stories and tests without a live conversation. Every token it names is on near.com's list. ```tsx title="approval.stories.tsx" import { ApprovalCard } from "@nearai/financial-agents-react"; import { oneShotApproval, oneShotContracts, PINNED_NOW } from "@nearai/financial-agents-react/fixtures"; export const PendingSwap = () => ( {}} now={PINNED_NOW} /> ); ``` | Group | Fixtures | | --- | --- | | Conversations | `fixtureEvents`, a named list of events per moment (`plainReply`, `thinking`, `streaming`, `toolRunning`, `approvalPending`, `ruleCreated`, `balancesThenSwap`, `ordersListed`, `gridStarted`, `gridsListed`, `runFailed` and more), named by `FixtureName`; `foldFixture(name)`, the thread they fold to; `foldConversation()`, several turns | | Trades to settlement | `executionFixtures`, a trade's endings (`settled`, `awaiting`, `partial`, `unconfirmed`, `failed`, `refused`), named by `ExecutionEnding`; `foldExecution(name)` at a step (`ExecutionStep`) or ending; `foldLateSettlement()`, `foldBuriedExecution()`, `lateSettlement`, `executionTimeline()`; `restrictedApprovalEvents(approve)`; `executionCardProps(thread)` | | Solana trades | `solanaCalls` (the calls the model proposes: `buyBonk`, `buyBonkTight`, `buyWithSol`, `buyNewCoin`, `buyLookalike`, `sellHalf`, `sellAllKeepSol`, `sellExact`, `fund`, `withdrawExact`, `withdrawAll`), `solanaApproval(call)` (a pending approval whose grant is the host's own derivation of the call), `solanaStandingApproval(definition)` with `solanaStandingDefinitions` (`dailyBonk`, `everySixHours`, `dipBuy`, `takeProfit`, `stopLoss`, `weeklySale`, `weeklyWithSol`, `datedBuy`, `newCoinDip`, `lookalikeDip`, `everyPriceUpdate`) and `solanaPriceRule(token, comparator, usd)` (an `automation_create` approval for a standing buy or sale), `solanaFixtureTokens(base)` (a resolver that knows three real mints by `solana:`, on top of `base`), `solanaPricedHoldings(wallet)` (a wallet's priced holdings with the prices a chat's Solana reads carry, which price a Solana ticket's estimates) and the mints `SOLANA_BONK`, `SOLANA_WIF`, `SOLANA_WIF_LOOKALIKE` and `SOLANA_NEW_COIN`; `foldSolanaBuy(step)`, `foldSolanaBuyEnding(outcome)`, `foldSolanaSell(outcome?)` and `foldSolanaReconciled()`, the thread after a purchase or sale reaches a step or ends as an outcome says, with `solanaBuyResults`, `solanaSellResults` and `solanaKeepSolResult` as the outcomes and `solanaTradeProps(thread)` for the card | | Approvals and contracts | `oneShotApproval(contract)` with `oneShotContracts` (`singleSwap`, `exactOutput`, `sellHalf`, `sendToThree`, `twoBuys` and more); `standingApproval(definition)` with `standingDefinitions` (each a `StandingDefinition`, `tloMonthlyHarvest` a vault deposit with a scheduled harvest), `perpsStandingDefinitions` (each a `PerpsStandingDefinition`: `reduceNearLiquidation`, `closeOnFunding`, `addMarginOnRatio`) and `pushExitDefinition`; `editApproval` (the frozen current/patch/result and carried allowance for a signed edit); `btcThresholdRule(usd)`, `tokenPriceThresholdRule(token, usd)`; `limitOrderPlaceApproval()`, `limitOrderCancelApproval()`, `limitOrderPlaceInput`, `limitOrderNearInput`, `limitOrderCancelInput`; `pricedHoldings`; `vaultRates` | | Solana reads | `SOLANA_TOKEN_SEARCH` (a search for `wif` that matched three tokens, two of them named WIF), `SOLANA_TOKEN_SEARCH_EXACT`, `SOLANA_TOKEN_LIST` and `SOLANA_TOKEN_LIST_NEW`, `SOLANA_TOKEN_DETAIL` and its variants (`_ON_CURVE`, `_NO_FLAGS`, `_BLOCKED`, `_UNKNOWN`), `SOLANA_ACCOUNT` and its variants (`_LOOKALIKES`, `_EMPTY`, `_UNREADABLE`), `SOLANA_NO_ACCOUNT` and `SOLANA_ACCOUNT_RECORD_UNAVAILABLE`: the four reads' results as the tools return them, each checked against the contract at load; `foldSolanaResearch()` folds a search, a list, a token read and the account into one conversation | | Prediction markets | `PREDICTION_SEARCH`, `PREDICTION_SETTLED_SEARCH`, `PREDICTION_MARKET`, `PREDICTION_SETTLED_MARKET`, `PREDICTION_PREVIEW`, `PREDICTION_PREVIEW_THIN`: the three reads' results as the tools return them; `predictionResearch` in `fixtureEvents` folds a search, a market read and a preview into one conversation | | Tokens | `USDC_ETH`, `USDC_NEAR`, `USDC_BASE`, `ETH`, `BTC`, `ZEC`, `NEAR`, `SOL`, `TLO` (Taler USDC's vault share), and `UNLISTED` (one the list lacks) | | Automations | `automationFixture()`, `finiteAutomationFixture()`, `contractAutomationFixture()`, `contractAutomationWith()`, `perpsAutomationFixture()`, `measurementAutomationFixture`, `webhookAutomationFixture`, `automationRunFixture()`, `simpleRule()`, `measurementAlertRule()`, `sourceCatalogFixture`, `sourcePlanFixture()` | | Grids | `gridFixture()` (a running grid: two buys and a sell resting, five idle cells, five cycles), `newGridFixture()` (just approved, its buys pending), `pausedGridFixture()`, `stoppedGridFixture()` | | Grid approvals | `gridCreateApproval()`, `gridCreateInput` (a ZEC grid: three buys below 1,158.09 USDC, five idle cells above), `gridHoldings` | | Pinned values | `PINNED_NOW` (the fixtures' clock), `EXPIRES_IN_MS`, `APPROVAL_ID`, `PANEL_WIDTH` (the cards' width in stories) | Solana execution views include optional `solanaProgress`: the latest `solana.progress` snapshot for the operation; a single-coin sale's carries `paid`, what its swap sold, once the swap landed, so a card need not estimate it from a balance read afterwards. `threadReducer` ignores an older or repeated revision and links its original `callId` to the tool row, including standing occurrences. A sale of several coins (`solana_sell_many`) also keeps `solanaSales`, each coin's latest swap snapshot by its `sale` (a `SolanaSaleProgress`). Funding receipts remain separate from native attempts; neither a funding receipt nor a confirmed native phase completes a buy or sale. Approval and tool blocks keep showing stages for an `in_progress` financial result after the model run ends, then use the operation's final outcome or reconciliation. A `solana_sell_many` approval is consent the packaged card never reads: the tool is offered only to a run whose app said it draws the sale (`context.renders`), so `approvalConsent` marks it `unreadable` (Cancel alone) and the app that asked for it draws its own card. `deriveApprovalState` still reads where it stands: `Selling coin 2 of 4` from its progress, then from its outcome `Done`, `Partly done: 3 of 4 coins sold` when the transfer back settled with a coin unsold, and the single sale's partly-done labels when the transfer back did not finish. --- # Tokens and chains Fin names tokens by their exact NEAR Intents id, such as `nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1`, and the agent wallet's holdings by an opaque id derived from it. `@nearai/financial-agents-react` turns those ids into what a person reads: USDC's symbol and icon, its network and that network's badge. ## What the package carries `DEFAULT_TOKENS` is near.com's production token list as a `TokenResolver`. Every block uses it unless you pass your own. | Data | Example | | --- | --- | | Every token near.com lists | Symbol, name, decimals, icon, chain, the group one asset's copies share across chains, and tags | | Every network's name and badge | `eth` reads as Ethereum, with a light and a dark mark where one would vanish | | The market listing behind each traded ticker | So an asset a reply names gets its icon even when the wallet doesn't hold it | > [!NOTE] > It is display data only. It never changes an amount, decimals or a price. A token the list lacks > keeps the provider's name and stays visible. A token is never identified by its symbol, so one > that merely shares a ticker never passes for the one you know. ## Content-Security-Policy Network badges, data providers' logos and the few token icons near.com hosts itself are inlined as `data:` URIs, so your app hosts nothing. Every other token icon loads from its public CDN. If your page sets a Content-Security-Policy, allow them in `img-src`: ```http Content-Security-Policy: img-src 'self' data: https://s2.coinmarketcap.com https://assets.coingecko.com https://cdn.ondo.finance https://dd.dexscreener.com https://ipfs.sintral.me https://near-intents.org ``` Drawing a reply asks no other third party for anything: a link to any other site shows its host beside a plain glyph. ## Draw a token `TokenIcon` draws a token's disc, badged with its network. Read its metadata from the configured list: ```tsx title="token-label.tsx" import { TokenIcon } from "@nearai/financial-agents-react"; import { assetChain, getTokenMetadata } from "@nearai/financial-agents-react/model"; export function TokenLabel({ tokenId }: { tokenId: string }) { const token = getTokenMetadata(tokenId); return ( {token?.symbol ?? tokenId} ); } ``` For a holding from `wallets.balances`, `AssetIcon` does this for you, and `holdingDisplay` returns the holding with the list's name, icon and network. ## Fin's opaque holding ids Holdings carry Fin's opaque `asset_…` ids, never token ids. `catalogTokenId` finds the token behind one when the list carries it; `finAssetId` derives Fin's id for a token, exactly as Fin does: ```ts import { catalogTokenId, finAssetId } from "@nearai/financial-agents-react/model"; const assetId = finAssetId("nep141:wrap.near"); console.log(catalogTokenId(assetId)); // "nep141:wrap.near" ``` ## Assets on portfolio rows [Get portfolio](/wallet-transfers#portfolio-and-its-history) holds assets from every account the agent owns, so each row's `asset` says which kind of asset it is: | `kind` | Field | What it is | | --- | --- | --- | | `token` | `assetId` | An agent wallet asset, by the same `asset_…` id Get balances uses | | `solana` | `mint` | A token in the agent's Solana account, by its mint address | | `sol` | none | Native SOL in the agent's Solana account | | `polymarket` | `tokenId` | Shares of a Polymarket outcome, by the `assetId` prediction orders use | | `usd` | none | US dollars: perps account equity, or Polymarket's pUSD | The row's `account` says where it is held, so two `usd` rows in different accounts are different holdings. `symbol` is `null` when no source names the asset, as for a Polymarket outcome: show your own label, such as the market's outcome. A Solana token's `iconUrl` is the path of [Get a token icon](/api-reference/solana/get-token-icon) on Fin's API. ## Networks | Function | Returns | | --- | --- | | `assetChain(tokenId)` | The chain a token comes from: the list's, or for a token it lacks, the one a canonical bridge id names (`nep141:eth-…`, `base-`, `arb-`, `sol-`). `null` otherwise, never a guess. | | `assetNetwork(tokenId)` | That chain's display name, such as `Ethereum`. | | `tokenNetworkName(chain)` | A chain key's display name; an unknown key reads as it is. | | `networkIcon(chain)` | A chain's badge as `{ light, dark }`, or `null`. | ## Use your own token list Pass your own `TokenResolver` to `FinUIProvider`, and on a server to `configureFinUI`. It replaces near.com's list. To add tokens to near.com's list instead, wrap it: ```tsx title="fin-tokens.tsx" import { FinUIProvider, type TokenInfo, type TokenResolver } from "@nearai/financial-agents-react"; import { DEFAULT_TOKENS } from "@nearai/financial-agents-react/model"; import type { ReactNode } from "react"; const MY_TOKENS = new Map([ [ "nep141:token.example.near", { tokenId: "nep141:token.example.near", symbol: "EXM", name: "Example", decimals: 18, icon: "https://example.com/exm.svg", chain: "near", unifiedAssetId: null, tags: [], }, ], ]); const tokens: TokenResolver = { ...DEFAULT_TOKENS, token: (tokenId) => MY_TOKENS.get(tokenId) ?? DEFAULT_TOKENS.token(tokenId), tokenIds: () => [...MY_TOKENS.keys(), ...DEFAULT_TOKENS.tokenIds()], }; export function FinTokens({ children }: { children: ReactNode }) { return {children}; } ``` > [!WARNING] > Treat a resolver as configuration: when your list changes, pass a new resolver object. Fin's > holding ids are matched against `tokenIds()` once per object, so a list that grows behind the > same object leaves new holdings unnamed. | Member | Returns | | --- | --- | | `token(tokenId)` | A `TokenInfo`: `tokenId`, `symbol`, `name`, `decimals`, `icon` (a URL or `data:` URI), `chain`, `unifiedAssetId` and `tags`. `undefined` for a token the list lacks, which reads as its shortened id. A Solana token is named by its mint as `solana:`, since a symbol is not unique on Solana; its `chain` is `solana`, and a mint the list lacks reads as its shortened mint, in a label only, never in full. | | `tokenIds()` | Every token id the list knows, to match Fin's holding ids. | | `networkName(chain)` | A chain key's display name. | | `networkIcon(chain)` | A chain's badge for light and dark, or `null`. | | `marketId(symbol)` | Optional. A ticker's market listing id, such as its CoinGecko id. | | `marketIcon(marketId)` | Optional. A market listing's icon. | The `category:earn-vault` tag marks tokens near.com keeps out of its regular asset lists; Fin's blocks show whatever the agent wallet holds. The `type:stablecoin` tag marks what prices are counted in. A limit order that pays with a tagged token reads as a buy of the other asset, priced per unit bought: `Buy NEAR with 10 USDC at ≤ 4 USDC per NEAR`. Without the tag, an order reads as the sale 1Click places. --- # Docs for AI agents Give your coding assistant access to the same guides and generated API reference you read here. The documentation server only reads public documentation; it cannot call the Fin API, access accounts, approve actions or move funds. ## Connect over MCP The docs server exposes a Streamable HTTP MCP endpoint at `/mcp`: ```text https://docs.fin.near.ai/mcp ``` Add that URL as a remote HTTP MCP server in your assistant's connection settings. Public documentation does not require your Fin partner key or an end-user token. The endpoint is available when the docs version containing this feature is deployed. For a local preview, replace the origin with the preview site's address and keep `/mcp`; a separate assistant can connect only if it can reach that address. ## Search, then read | Tool | Input | Use | | --- | --- | --- | | `search_docs` | `{ "query": "approval continuation" }` | Find matching pages. | | `get_doc` | `{ "id": "" }` | Read a matching page's full Markdown. | Search for a task or resource, then pass a returned page id to `get_doc`. Use endpoint schemas for request and response fields, and guides for workflows across calls. The server reads the documentation packaged with that deployment. A local preview can contain changes that have not yet reached the public site. For example, ask your assistant: > Use the Fin documentation MCP to explain how to start a run and reconnect to its event > stream. Read the authentication and streaming guides, then check the endpoint schemas > before writing the integration. ## Copy or fetch Markdown Use **Copy page** to copy a page's Markdown. Its `.md` URL exposes the same content without navigation or styling, for example: ```text https://docs.fin.near.ai/quickstart.md https://docs.fin.near.ai/api-reference/runs/start.md ``` [llms.txt](/llms.txt) provides a compact page index. [llms-full.txt](/llms-full.txt) provides the documentation as one text file. Use [OpenAPI](/openapi.json) for the machine-readable API schema. ## Keep credentials in your application Documentation access requires no API credentials. When moving to real requests, keep your partner key and user token in your trusted application environment. Follow [Authentication](/authentication) and [Your first run](/quickstart) for the separate steps needed to call Fin. --- # Open a perps account 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. `POST /v1/users/{userId}/perps/account` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/perps/account' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' ``` ## Responses ### 200 The user's perps account. ```json { "description": "The user's perps account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerpsAccount" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `perps_disabled` — perps is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `perps_disabled` — perps is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account ```json { "description": "The operation lost to the current state.\n\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "perps.openAccount", "summary": "Open a perps account", "tags": [ "perps" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's perps account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerpsAccount" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `perps_disabled` — perps is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "PerpsAccount": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "The agent's Hyperliquid address, as lowercase hexadecimal." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the perps account was first opened." }, "state": { "$ref": "#/components/schemas/PerpsAccountState" } }, "required": [ "address", "createdAt", "state" ], "description": "The agent's Hyperliquid perpetuals account and its current venue observation." }, "PerpsAccountState": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "The venue returned a valid account observation." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this account state was read." }, "accountValueUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Account value in US dollars, across Hyperliquid's main dex and trade.xyz." }, "withdrawableUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Withdrawable value in US dollars, across Hyperliquid's main dex and trade.xyz." }, "marginUsedUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Margin in use in US dollars, across Hyperliquid's main dex and trade.xyz." }, "positionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The number of positions with a nonzero size, on either dex." }, "positions": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PerpsPosition" }, "description": "Each open position on either dex, largest `positionValueUsd` first, at most 100; `positionCount` counts them all. Their unrealized PnL is already in `accountValueUsd`, so never add their value to it." } }, "required": [ "status", "observedAt", "accountValueUsd", "withdrawableUsd", "marginUsedUsd", "positionCount", "positions" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "The account state could not be observed." }, "reason": { "type": "string", "enum": [ "provider_unavailable", "invalid_response" ], "description": "Why the venue observation is unavailable." } }, "required": [ "status", "reason" ] } ], "description": "A live observation of the perps account, or why its state could not be read." }, "PerpsPosition": { "type": "object", "properties": { "coin": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The market's coin name as Hyperliquid lists it, such as `BTC`, or `xyz:TSLA` on trade.xyz." }, "size": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Signed size in the coin: positive for a long position, negative for a short one." }, "entryPriceUsd": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, { "type": "null" } ], "description": "Average entry price in US dollars; null when Hyperliquid reports none, not zero." }, "positionValueUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "What the position is worth at the mark price, in US dollars: its notional, not equity." }, "unrealizedPnlUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Unrealized profit (positive) or loss (negative) in US dollars, already part of `accountValueUsd`." }, "fundingSinceOpenUsd": { "description": "Funding paid by the whole position since it opened, in US dollars; positive is paid, negative is received. Absent when the venue did not report it.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "marginUsedUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Margin this position holds, in US dollars." }, "liquidationPriceUsd": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, { "type": "null" } ], "description": "Price at which Hyperliquid liquidates the position; null when there is none." }, "leverage": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The position's leverage multiplier." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "`cross` shares its dex's account margin with every cross position there; `isolated` holds its own." } }, "required": [ "coin", "size", "entryPriceUsd", "positionValueUsd", "unrealizedPnlUsd", "marginUsedUsd", "liquidationPriceUsd", "leverage", "marginMode" ], "description": "One open perpetual position, as Hyperliquid reported it with the account." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a perps account 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. `GET /v1/users/{userId}/perps/account` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/perps/account' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The user's perps account and its live state. ```json { "description": "The user's perps account and its live state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerpsAccount" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "perps.getAccount", "summary": "Get a perps account", "tags": [ "perps" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's perps account and its live state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerpsAccount" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "PerpsAccount": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "The agent's Hyperliquid address, as lowercase hexadecimal." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the perps account was first opened." }, "state": { "$ref": "#/components/schemas/PerpsAccountState" } }, "required": [ "address", "createdAt", "state" ], "description": "The agent's Hyperliquid perpetuals account and its current venue observation." }, "PerpsAccountState": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "The venue returned a valid account observation." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this account state was read." }, "accountValueUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Account value in US dollars, across Hyperliquid's main dex and trade.xyz." }, "withdrawableUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Withdrawable value in US dollars, across Hyperliquid's main dex and trade.xyz." }, "marginUsedUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Margin in use in US dollars, across Hyperliquid's main dex and trade.xyz." }, "positionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The number of positions with a nonzero size, on either dex." }, "positions": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PerpsPosition" }, "description": "Each open position on either dex, largest `positionValueUsd` first, at most 100; `positionCount` counts them all. Their unrealized PnL is already in `accountValueUsd`, so never add their value to it." } }, "required": [ "status", "observedAt", "accountValueUsd", "withdrawableUsd", "marginUsedUsd", "positionCount", "positions" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "The account state could not be observed." }, "reason": { "type": "string", "enum": [ "provider_unavailable", "invalid_response" ], "description": "Why the venue observation is unavailable." } }, "required": [ "status", "reason" ] } ], "description": "A live observation of the perps account, or why its state could not be read." }, "PerpsPosition": { "type": "object", "properties": { "coin": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The market's coin name as Hyperliquid lists it, such as `BTC`, or `xyz:TSLA` on trade.xyz." }, "size": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Signed size in the coin: positive for a long position, negative for a short one." }, "entryPriceUsd": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, { "type": "null" } ], "description": "Average entry price in US dollars; null when Hyperliquid reports none, not zero." }, "positionValueUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "What the position is worth at the mark price, in US dollars: its notional, not equity." }, "unrealizedPnlUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Unrealized profit (positive) or loss (negative) in US dollars, already part of `accountValueUsd`." }, "fundingSinceOpenUsd": { "description": "Funding paid by the whole position since it opened, in US dollars; positive is paid, negative is received. Absent when the venue did not report it.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "marginUsedUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Margin this position holds, in US dollars." }, "liquidationPriceUsd": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, { "type": "null" } ], "description": "Price at which Hyperliquid liquidates the position; null when there is none." }, "leverage": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The position's leverage multiplier." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "`cross` shares its dex's account margin with every cross position there; `isolated` holds its own." } }, "required": [ "coin", "size", "entryPriceUsd", "positionValueUsd", "unrealizedPnlUsd", "marginUsedUsd", "liquidationPriceUsd", "leverage", "marginMode" ], "description": "One open perpetual position, as Hyperliquid reported it with the account." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Open a prediction-market account 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. `POST /v1/users/{userId}/prediction/account` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/prediction/account' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' ``` ## Responses ### 200 The user's prediction-market account. ```json { "description": "The user's prediction-market account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredictionAccount" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `prediction_disabled` — prediction-market trading is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `prediction_disabled` — prediction-market trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account ```json { "description": "The operation lost to the current state.\n\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "prediction.openAccount", "summary": "Open a prediction-market account", "tags": [ "prediction" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's prediction-market account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredictionAccount" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `prediction_disabled` — prediction-market trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "PredictionAccount": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "The agent's Polymarket Deposit Wallet on Polygon, which holds its pUSD and positions." }, "signer": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "The address of the key that controls the wallet. Fin holds the key; funds stay in the wallet." }, "status": { "type": "string", "enum": [ "opening", "ready" ], "description": "`opening` while Polymarket's relayer creates the wallet and sets its trading approvals; `ready` once Polygon shows both." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the account was first opened." }, "balance": { "$ref": "#/components/schemas/PredictionAccountBalance" }, "positions": { "$ref": "#/components/schemas/PredictionAccountPositions" } }, "required": [ "address", "signer", "status", "createdAt", "balance", "positions" ], "description": "The agent's Polymarket account, its live pUSD balance and its positions." }, "PredictionAccountBalance": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "Polygon answered for the wallet's balance." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the balance was read." }, "pusd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "pUSD (Polymarket USD, backed one to one by USDC) the wallet holds, as an exact decimal." } }, "required": [ "status", "observedAt", "pusd" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "The balance could not be read." }, "reason": { "type": "string", "enum": [ "provider_unavailable", "invalid_response" ], "description": "Why the balance could not be read." } }, "required": [ "status", "reason" ] } ], "description": "The wallet's pUSD balance read from Polygon, or why it could not be read." }, "PredictionAccountPositions": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "Polymarket answered for the wallet's positions." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin read the positions: the time of this read, or of the last one when `stale` is true." }, "stale": { "type": "boolean", "description": "True when Polymarket rate-limited this read and these are the last positions Fin read within the past hour, as of `observedAt`. They may no longer be what the wallet holds: show them as last known with their time, and never size a sale or set a maximum from them." }, "positions": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PredictionPosition" }, "description": "Each open position, settled winners not yet redeemed included, largest `currentValueUsdDecimal` first." }, "truncated": { "type": "boolean", "description": "True when the wallet holds more than the 100 positions listed, so their values do not add up to everything it holds." } }, "required": [ "status", "observedAt", "stale", "positions", "truncated" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "The positions could not be read." }, "reason": { "type": "string", "enum": [ "provider_unavailable", "invalid_response" ], "description": "Why the positions could not be read." } }, "required": [ "status", "reason" ] } ], "description": "The wallet's Polymarket positions, read from Polymarket's data API, or why they could not be read." }, "PredictionPosition": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$", "description": "The outcome token's id, the `assetId` a prediction order names." }, "marketQuestion": { "type": "string", "maxLength": 500, "description": "The market's question, as Polymarket titles it." }, "outcome": { "type": "string", "maxLength": 200, "description": "The outcome these shares pay on, such as `Yes`." }, "sizeSharesDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Shares held, as an exact decimal." }, "averagePriceUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Average price paid per share, in US dollars." }, "currentPriceUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Polymarket's current price per share, in US dollars." }, "currentValueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "What the shares are worth at the current price, in US dollars." }, "costUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "What the shares cost, in US dollars." }, "unrealizedPnlUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Current value less cost, in US dollars: positive for a gain, negative for a loss." }, "redeemable": { "type": "boolean", "description": "The market settled for this outcome and its winning shares await redemption." } }, "required": [ "assetId", "marketQuestion", "outcome", "sizeSharesDecimal", "averagePriceUsdDecimal", "currentPriceUsdDecimal", "currentValueUsdDecimal", "costUsdDecimal", "unrealizedPnlUsdDecimal", "redeemable" ], "description": "One Polymarket position the wallet holds, valued as Polymarket shows it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a prediction-market account 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. `GET /v1/users/{userId}/prediction/account` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/prediction/account' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The user's prediction-market account, its live balance and its positions. ```json { "description": "The user's prediction-market account, its live balance and its positions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredictionAccount" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "prediction.getAccount", "summary": "Get a prediction-market account", "tags": [ "prediction" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's prediction-market account, its live balance and its positions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredictionAccount" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "PredictionAccount": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "The agent's Polymarket Deposit Wallet on Polygon, which holds its pUSD and positions." }, "signer": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "The address of the key that controls the wallet. Fin holds the key; funds stay in the wallet." }, "status": { "type": "string", "enum": [ "opening", "ready" ], "description": "`opening` while Polymarket's relayer creates the wallet and sets its trading approvals; `ready` once Polygon shows both." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the account was first opened." }, "balance": { "$ref": "#/components/schemas/PredictionAccountBalance" }, "positions": { "$ref": "#/components/schemas/PredictionAccountPositions" } }, "required": [ "address", "signer", "status", "createdAt", "balance", "positions" ], "description": "The agent's Polymarket account, its live pUSD balance and its positions." }, "PredictionAccountBalance": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "Polygon answered for the wallet's balance." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the balance was read." }, "pusd": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "pUSD (Polymarket USD, backed one to one by USDC) the wallet holds, as an exact decimal." } }, "required": [ "status", "observedAt", "pusd" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "The balance could not be read." }, "reason": { "type": "string", "enum": [ "provider_unavailable", "invalid_response" ], "description": "Why the balance could not be read." } }, "required": [ "status", "reason" ] } ], "description": "The wallet's pUSD balance read from Polygon, or why it could not be read." }, "PredictionAccountPositions": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "Polymarket answered for the wallet's positions." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin read the positions: the time of this read, or of the last one when `stale` is true." }, "stale": { "type": "boolean", "description": "True when Polymarket rate-limited this read and these are the last positions Fin read within the past hour, as of `observedAt`. They may no longer be what the wallet holds: show them as last known with their time, and never size a sale or set a maximum from them." }, "positions": { "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PredictionPosition" }, "description": "Each open position, settled winners not yet redeemed included, largest `currentValueUsdDecimal` first." }, "truncated": { "type": "boolean", "description": "True when the wallet holds more than the 100 positions listed, so their values do not add up to everything it holds." } }, "required": [ "status", "observedAt", "stale", "positions", "truncated" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "The positions could not be read." }, "reason": { "type": "string", "enum": [ "provider_unavailable", "invalid_response" ], "description": "Why the positions could not be read." } }, "required": [ "status", "reason" ] } ], "description": "The wallet's Polymarket positions, read from Polymarket's data API, or why they could not be read." }, "PredictionPosition": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$", "description": "The outcome token's id, the `assetId` a prediction order names." }, "marketQuestion": { "type": "string", "maxLength": 500, "description": "The market's question, as Polymarket titles it." }, "outcome": { "type": "string", "maxLength": 200, "description": "The outcome these shares pay on, such as `Yes`." }, "sizeSharesDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Shares held, as an exact decimal." }, "averagePriceUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Average price paid per share, in US dollars." }, "currentPriceUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Polymarket's current price per share, in US dollars." }, "currentValueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "What the shares are worth at the current price, in US dollars." }, "costUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "What the shares cost, in US dollars." }, "unrealizedPnlUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Current value less cost, in US dollars: positive for a gain, negative for a loss." }, "redeemable": { "type": "boolean", "description": "The market settled for this outcome and its winning shares await redemption." } }, "required": [ "assetId", "marketQuestion", "outcome", "sizeSharesDecimal", "averagePriceUsdDecimal", "currentPriceUsdDecimal", "currentValueUsdDecimal", "costUsdDecimal", "unrealizedPnlUsdDecimal", "redeemable" ], "description": "One Polymarket position the wallet holds, valued as Polymarket shows it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Prepare a Polymarket order 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`. `POST /v1/users/{userId}/prediction/orders/prepare` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredictionOrderInputInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/prediction/orders/prepare' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The order, the message to sign and the request key. ```json { "description": "The order, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedPredictionOrder" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `prediction_disabled` — prediction-market trading is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `prediction_disabled` — prediction-market trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. - `no_account` — the user has not opened the account this call reads; open it first ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "prediction.prepareOrder", "summary": "Prepare a Polymarket order", "tags": [ "prediction" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PredictionOrderInputInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The order, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedPredictionOrder" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `prediction_disabled` — prediction-market trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "PredictionOrderInputInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ], "additionalProperties": false } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ], "additionalProperties": false }, "PreparedPredictionOrder": { "type": "object", "properties": { "order": { "description": "The exact order to show the user and send, unchanged, to Place a Polymarket order.", "$ref": "#/components/schemas/PredictionOrderInput" }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This order's id for retries: send it as the `Idempotency-Key` of Place a Polymarket order." }, "authorization": { "description": "The message the user signs to allow exactly this order. Call Place a Polymarket order before `authorization.expiresAt`.", "$ref": "#/components/schemas/MessageToSign" } }, "required": [ "order", "requestKey", "authorization" ], "description": "A Polymarket order's exact terms, the message the user signs for them, and the key to place it with." }, "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "MessageToSign": { "type": "object", "properties": { "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "message", "controllerId", "expiresAt" ], "description": "A message for the user to sign with their registered wallet or passkey, and the values to send back with the signature." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Place a Polymarket order 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. `POST /v1/users/{userId}/prediction/orders` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The prepared order's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same order back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacePredictionOrderInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/prediction/orders' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The order and its latest fills. ```json { "description": "The order and its latest fills.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "observation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "live", "partially_filled", "matched", "filled", "cancelled", "expired", "rejected", "uncertain" ] }, "originalSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "matchedSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "remainingSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tradeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED" ] }, "sizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "tradeId", "status", "sizeRaw" ] } }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settledCollateralRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "settledFeeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "cancelRequested": { "type": "boolean" }, "polymarketError": { "description": "What Polymarket answered when the order was sent, when it answered with an error: kept with the order for good. Absent when Polymarket gave no reason.", "type": "object", "properties": { "httpStatus": { "description": "The HTTP status Polymarket answered with, when it answered with an error status.", "type": "integer", "minimum": 100, "maximum": 599 }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Polymarket's own words, exactly as it answered, cut to their first 300 characters." } }, "required": [ "message" ] }, "venueOrderId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "status", "originalSizeRaw", "matchedSizeRaw", "remainingSizeRaw", "trades", "observedAtMs", "venueOrderId" ] } }, "required": [ "id", "order", "observation" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `prediction_disabled` — prediction-market trading is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `prediction_disabled` — prediction-market trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. - `no_account` — the user has not opened the account this call reads; open it first ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `prediction_order_changed` — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `prediction_order_changed` — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "prediction.placeOrder", "summary": "Place a Polymarket order", "tags": [ "prediction" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacePredictionOrderInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The prepared order's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same order back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The order and its latest fills.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "observation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "live", "partially_filled", "matched", "filled", "cancelled", "expired", "rejected", "uncertain" ] }, "originalSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "matchedSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "remainingSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tradeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED" ] }, "sizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "tradeId", "status", "sizeRaw" ] } }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settledCollateralRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "settledFeeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "cancelRequested": { "type": "boolean" }, "polymarketError": { "description": "What Polymarket answered when the order was sent, when it answered with an error: kept with the order for good. Absent when Polymarket gave no reason.", "type": "object", "properties": { "httpStatus": { "description": "The HTTP status Polymarket answered with, when it answered with an error status.", "type": "integer", "minimum": 100, "maximum": 599 }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Polymarket's own words, exactly as it answered, cut to their first 300 characters." } }, "required": [ "message" ] }, "venueOrderId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "status", "originalSizeRaw", "matchedSizeRaw", "remainingSizeRaw", "trades", "observedAtMs", "venueOrderId" ] } }, "required": [ "id", "order", "observation" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `prediction_disabled` — prediction-market trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "The operation lost to the current state.\n\n- `prediction_order_changed` — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "PlacePredictionOrderInput": { "type": "object", "properties": { "order": { "description": "The prepared order, unchanged.", "$ref": "#/components/schemas/PredictionOrderInputInput" }, "authorization": { "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false, "description": "The user's signature of the prepared order's `authorization.message`, with its `controllerId` and `expiresAt` unchanged. Checked on arrival and never stored." } }, "required": [ "order", "authorization" ], "additionalProperties": false }, "PredictionOrderInputInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ], "additionalProperties": false } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ], "additionalProperties": false }, "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List prediction orders 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 /v1/users/{userId}/prediction/orders` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/prediction/orders' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of prediction orders. ```json { "description": "A page of prediction orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "observation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "live", "partially_filled", "matched", "filled", "cancelled", "expired", "rejected", "uncertain" ] }, "originalSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "matchedSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "remainingSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tradeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED" ] }, "sizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "tradeId", "status", "sizeRaw" ] } }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settledCollateralRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "settledFeeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "cancelRequested": { "type": "boolean" }, "polymarketError": { "description": "What Polymarket answered when the order was sent, when it answered with an error: kept with the order for good. Absent when Polymarket gave no reason.", "type": "object", "properties": { "httpStatus": { "description": "The HTTP status Polymarket answered with, when it answered with an error status.", "type": "integer", "minimum": 100, "maximum": 599 }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Polymarket's own words, exactly as it answered, cut to their first 300 characters." } }, "required": [ "message" ] }, "venueOrderId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "status", "originalSizeRaw", "matchedSizeRaw", "remainingSizeRaw", "trades", "observedAtMs", "venueOrderId" ] } }, "required": [ "id", "order", "observation" ] }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "prediction.listOrders", "summary": "List prediction orders", "tags": [ "prediction" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of prediction orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "observation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "live", "partially_filled", "matched", "filled", "cancelled", "expired", "rejected", "uncertain" ] }, "originalSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "matchedSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "remainingSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tradeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED" ] }, "sizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "tradeId", "status", "sizeRaw" ] } }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settledCollateralRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "settledFeeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "cancelRequested": { "type": "boolean" }, "polymarketError": { "description": "What Polymarket answered when the order was sent, when it answered with an error: kept with the order for good. Absent when Polymarket gave no reason.", "type": "object", "properties": { "httpStatus": { "description": "The HTTP status Polymarket answered with, when it answered with an error status.", "type": "integer", "minimum": 100, "maximum": 599 }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Polymarket's own words, exactly as it answered, cut to their first 300 characters." } }, "required": [ "message" ] }, "venueOrderId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "status", "originalSizeRaw", "matchedSizeRaw", "remainingSizeRaw", "trades", "observedAtMs", "venueOrderId" ] } }, "required": [ "id", "order", "observation" ] }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a prediction order 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. `GET /v1/users/{userId}/prediction/orders/{orderId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "orderId", "required": true } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/prediction/orders/YOUR_ORDER_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The prediction order and its current fills. ```json { "description": "The prediction order and its current fills.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "observation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "live", "partially_filled", "matched", "filled", "cancelled", "expired", "rejected", "uncertain" ] }, "originalSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "matchedSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "remainingSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tradeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED" ] }, "sizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "tradeId", "status", "sizeRaw" ] } }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settledCollateralRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "settledFeeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "cancelRequested": { "type": "boolean" }, "polymarketError": { "description": "What Polymarket answered when the order was sent, when it answered with an error: kept with the order for good. Absent when Polymarket gave no reason.", "type": "object", "properties": { "httpStatus": { "description": "The HTTP status Polymarket answered with, when it answered with an error status.", "type": "integer", "minimum": 100, "maximum": 599 }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Polymarket's own words, exactly as it answered, cut to their first 300 characters." } }, "required": [ "message" ] }, "venueOrderId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "status", "originalSizeRaw", "matchedSizeRaw", "remainingSizeRaw", "trades", "observedAtMs", "venueOrderId" ] } }, "required": [ "id", "order", "observation" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "prediction.getOrder", "summary": "Get a prediction order", "tags": [ "prediction" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "orderId", "required": true } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The prediction order and its current fills.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "observation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "live", "partially_filled", "matched", "filled", "cancelled", "expired", "rejected", "uncertain" ] }, "originalSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "matchedSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "remainingSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tradeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED" ] }, "sizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "tradeId", "status", "sizeRaw" ] } }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settledCollateralRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "settledFeeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "cancelRequested": { "type": "boolean" }, "polymarketError": { "description": "What Polymarket answered when the order was sent, when it answered with an error: kept with the order for good. Absent when Polymarket gave no reason.", "type": "object", "properties": { "httpStatus": { "description": "The HTTP status Polymarket answered with, when it answered with an error status.", "type": "integer", "minimum": 100, "maximum": 599 }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Polymarket's own words, exactly as it answered, cut to their first 300 characters." } }, "required": [ "message" ] }, "venueOrderId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "status", "originalSizeRaw", "matchedSizeRaw", "remainingSizeRaw", "trades", "observedAtMs", "venueOrderId" ] } }, "required": [ "id", "order", "observation" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Cancel a prediction order 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. `POST /v1/users/{userId}/prediction/orders/{orderId}/cancel` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "orderId", "required": true } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/prediction/orders/YOUR_ORDER_ID/cancel' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The order after requesting cancellation. ```json { "description": "The order after requesting cancellation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "observation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "live", "partially_filled", "matched", "filled", "cancelled", "expired", "rejected", "uncertain" ] }, "originalSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "matchedSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "remainingSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tradeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED" ] }, "sizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "tradeId", "status", "sizeRaw" ] } }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settledCollateralRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "settledFeeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "cancelRequested": { "type": "boolean" }, "polymarketError": { "description": "What Polymarket answered when the order was sent, when it answered with an error: kept with the order for good. Absent when Polymarket gave no reason.", "type": "object", "properties": { "httpStatus": { "description": "The HTTP status Polymarket answered with, when it answered with an error status.", "type": "integer", "minimum": 100, "maximum": 599 }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Polymarket's own words, exactly as it answered, cut to their first 300 characters." } }, "required": [ "message" ] }, "venueOrderId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "status", "originalSizeRaw", "matchedSizeRaw", "remainingSizeRaw", "trades", "observedAtMs", "venueOrderId" ] } }, "required": [ "id", "order", "observation" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "prediction.cancelOrder", "summary": "Cancel a prediction order", "tags": [ "prediction" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "orderId", "required": true } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The order after requesting cancellation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "observation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "live", "partially_filled", "matched", "filled", "cancelled", "expired", "rejected", "uncertain" ] }, "originalSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "matchedSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "remainingSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tradeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED" ] }, "sizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "tradeId", "status", "sizeRaw" ] } }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settledCollateralRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "settledFeeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "cancelRequested": { "type": "boolean" }, "polymarketError": { "description": "What Polymarket answered when the order was sent, when it answered with an error: kept with the order for good. Absent when Polymarket gave no reason.", "type": "object", "properties": { "httpStatus": { "description": "The HTTP status Polymarket answered with, when it answered with an error status.", "type": "integer", "minimum": 100, "maximum": 599 }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Polymarket's own words, exactly as it answered, cut to their first 300 characters." } }, "required": [ "message" ] }, "venueOrderId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "status", "originalSizeRaw", "matchedSizeRaw", "remainingSizeRaw", "trades", "observedAtMs", "venueOrderId" ] } }, "required": [ "id", "order", "observation" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Prepare a Solana trade 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`. `POST /v1/users/{userId}/solana/trades/prepare` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTradeRequestInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/solana/trades/prepare' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The trade, the message to sign and the request key. ```json { "description": "The trade, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedSolanaTrade" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `solana_disabled` — Solana trading is not enabled for this user - `solana_token_not_tradable` — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing - `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user\n- `solana_token_not_tradable` — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. - `no_account` — the user has not opened the account this call reads; open it first ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `solana_trade_changed` — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again - `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account ```json { "description": "The operation lost to the current state.\n\n- `solana_trade_changed` — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.prepareTrade", "summary": "Prepare a Solana trade", "tags": [ "solana" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTradeRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The trade, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedSolanaTrade" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user\n- `solana_token_not_tradable` — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "The operation lost to the current state.\n\n- `solana_trade_changed` — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "SolanaTradeRequestInput": { "oneOf": [ { "type": "object", "properties": { "side": { "type": "string", "const": "buy", "description": "Buy the token." }, "buy": { "description": "The exact buy: the token, what it pays, its all-in loss bound and its SOL top-up cap.", "$ref": "#/components/schemas/SolanaBuyInputInput" } }, "required": [ "side", "buy" ], "additionalProperties": false }, { "type": "object", "properties": { "side": { "type": "string", "const": "sell", "description": "Sell the token." }, "sell": { "description": "The exact sale: the token, how much of it, where the proceeds go and its all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInputInput" } }, "required": [ "side", "sell" ], "additionalProperties": false } ], "description": "A buy or a sale of one Solana token through the agent's own Solana account." }, "SolanaBuyInputInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaTokenInput" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "additionalProperties": false, "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPaymentInput" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "additionalProperties": false, "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaTokenInput": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "additionalProperties": false, "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPaymentInput": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "additionalProperties": false, "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaSellInputInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaTokenInput" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "additionalProperties": false, "description": "One sell of a Solana token held in the agent's own Solana account." }, "PreparedSolanaTrade": { "type": "object", "properties": { "trade": { "description": "The exact trade to show the user and send, unchanged, to Place a Solana trade.", "$ref": "#/components/schemas/SolanaTradeRequest" }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This trade's id for retries: send it as the `Idempotency-Key` of Place a Solana trade." }, "authorization": { "description": "The message the user signs to allow exactly this trade. Call Place a Solana trade before `authorization.expiresAt`. A trade that starts by then may take up to nine more minutes to finish; the message names that time.", "$ref": "#/components/schemas/MessageToSign" } }, "required": [ "trade", "requestKey", "authorization" ], "description": "A Solana trade's exact terms, the message the user signs for them, and the key to place it with." }, "SolanaTradeRequest": { "oneOf": [ { "type": "object", "properties": { "side": { "type": "string", "const": "buy", "description": "Buy the token." }, "buy": { "description": "The exact buy: the token, what it pays, its all-in loss bound and its SOL top-up cap.", "$ref": "#/components/schemas/SolanaBuyInput" } }, "required": [ "side", "buy" ] }, { "type": "object", "properties": { "side": { "type": "string", "const": "sell", "description": "Sell the token." }, "sell": { "description": "The exact sale: the token, how much of it, where the proceeds go and its all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" } }, "required": [ "side", "sell" ] } ], "description": "A buy or a sale of one Solana token through the agent's own Solana account." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "MessageToSign": { "type": "object", "properties": { "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "message", "controllerId", "expiresAt" ], "description": "A message for the user to sign with their registered wallet or passkey, and the values to send back with the signature." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Place a Solana trade 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. `POST /v1/users/{userId}/solana/trades` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The prepared trade's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same trade back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceSolanaTradeInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/solana/trades' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 201 The trade, as Get a Solana trade returns it. ```json { "description": "The trade, as Get a Solana trade returns it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTrade" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `solana_disabled` — Solana trading is not enabled for this user - `solana_token_not_tradable` — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing - `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user\n- `solana_token_not_tradable` — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. - `no_account` — the user has not opened the account this call reads; open it first ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `solana_trade_changed` — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again - `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `solana_trade_changed` — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.placeTrade", "summary": "Place a Solana trade", "tags": [ "solana" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceSolanaTradeInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The prepared trade's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same trade back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "201": { "description": "The trade, as Get a Solana trade returns it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTrade" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user\n- `solana_token_not_tradable` — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "The operation lost to the current state.\n\n- `solana_trade_changed` — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "PlaceSolanaTradeInput": { "type": "object", "properties": { "trade": { "description": "The prepared trade, unchanged.", "$ref": "#/components/schemas/SolanaTradeRequestInput" }, "authorization": { "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false, "description": "The user's signature of the prepared trade's `authorization.message`, with its `controllerId` and `expiresAt` unchanged. Checked on arrival and never stored." } }, "required": [ "trade", "authorization" ], "additionalProperties": false }, "SolanaTradeRequestInput": { "oneOf": [ { "type": "object", "properties": { "side": { "type": "string", "const": "buy", "description": "Buy the token." }, "buy": { "description": "The exact buy: the token, what it pays, its all-in loss bound and its SOL top-up cap.", "$ref": "#/components/schemas/SolanaBuyInputInput" } }, "required": [ "side", "buy" ], "additionalProperties": false }, { "type": "object", "properties": { "side": { "type": "string", "const": "sell", "description": "Sell the token." }, "sell": { "description": "The exact sale: the token, how much of it, where the proceeds go and its all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInputInput" } }, "required": [ "side", "sell" ], "additionalProperties": false } ], "description": "A buy or a sale of one Solana token through the agent's own Solana account." }, "SolanaBuyInputInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaTokenInput" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "additionalProperties": false, "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPaymentInput" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "additionalProperties": false, "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaTokenInput": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "additionalProperties": false, "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPaymentInput": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "additionalProperties": false, "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaSellInputInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaTokenInput" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "additionalProperties": false, "description": "One sell of a Solana token held in the agent's own Solana account." }, "SolanaTrade": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id, for Get a Solana trade." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` it was placed under." }, "trade": { "description": "The trade as the user signed it.", "$ref": "#/components/schemas/SolanaTradeRequest" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "partial", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, usually while it waits for the user's approval. `processing` while it runs, or while a Solana transaction it sent, or its transfer back to the agent wallet, has not finished. Then `completed` (the tokens bought, the proceeds of a sale or the SOL moved arrived), `partial` (part of it stands: a buy whose swap never happened after the account was funded, so the SOL is in the agent's Solana account, or a sale whose swap landed but whose transfer back did not finish, or that kept SOL, so the SOL is in the account or with 1Click until it refunds it; `solLeftLamports` says how much the account holds), `refunded` (1Click sent the funds back where they came from) or `failed` (nothing moved; `failureReason` says why). `denied` and `expired` mean the user denied it, or its approval ran out, before it started. `uncertain` means the result could not be confirmed yet: never ask the agent for a replacement, keep checking. `completed`, `partial`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the agent wallet or the Solana account did not hold enough, the account's reserve included. `quote_rejected`: the price or the route failed its checks, the loss limit would have been crossed, or a buy was under the minimum. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the approval no longer covered it, or the token is one the agent does not trade. `stopped`: an operator paused trading or turned the wallet off. `not_executed`: nothing it sent landed before it expired. `signing_disabled`: this deployment does not sign trades. In every case nothing moved." }, "stage": { "description": "The step it is on, once it started: `funding` moves USDC from the agent wallet to the Solana account as SOL through 1Click, `swap` trades on Jupiter, `sweep` sends a sale's SOL back to the agent wallet. A higher `revision` is newer.", "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1, "maximum": 1024, "description": "Persisted lifecycle stage number. Ignore an older snapshot for the same operation." }, "phase": { "type": "string", "enum": [ "funding", "swap", "sweep" ] }, "state": { "type": "string", "enum": [ "preparing", "prepared", "submitting", "pending", "delivering", "confirmed", "uncertain", "refunded", "failed", "not_executed" ] }, "transactionIndex": { "description": "The stored native transaction attempt, never a funding plan leg index.", "type": "integer", "minimum": 0, "maximum": 5 } }, "required": [ "revision", "phase", "state" ] }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "completeBy": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest it may still run, as the user signed it; its status is final by then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was placed." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When its records last changed." } }, "required": [ "id", "requestKey", "trade", "status", "failureReason", "transactions", "completeBy", "createdAt", "updatedAt" ], "description": "A Solana buy or sale the user placed themselves: its status, the step it is on, and what it paid and received." }, "SolanaTradeRequest": { "oneOf": [ { "type": "object", "properties": { "side": { "type": "string", "const": "buy", "description": "Buy the token." }, "buy": { "description": "The exact buy: the token, what it pays, its all-in loss bound and its SOL top-up cap.", "$ref": "#/components/schemas/SolanaBuyInput" } }, "required": [ "side", "buy" ] }, { "type": "object", "properties": { "side": { "type": "string", "const": "sell", "description": "Sell the token." }, "sell": { "description": "The exact sale: the token, how much of it, where the proceeds go and its all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" } }, "required": [ "side", "sell" ] } ], "description": "A buy or a sale of one Solana token through the agent's own Solana account." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a Solana trade 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. `GET /v1/users/{userId}/solana/trades/{tradeId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tradeId", "required": true } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/solana/trades/YOUR_TRADE_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The Solana trade. ```json { "description": "The Solana trade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTrade" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.getTrade", "summary": "Get a Solana trade", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tradeId", "required": true } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The Solana trade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTrade" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "SolanaTrade": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id, for Get a Solana trade." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` it was placed under." }, "trade": { "description": "The trade as the user signed it.", "$ref": "#/components/schemas/SolanaTradeRequest" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "partial", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, usually while it waits for the user's approval. `processing` while it runs, or while a Solana transaction it sent, or its transfer back to the agent wallet, has not finished. Then `completed` (the tokens bought, the proceeds of a sale or the SOL moved arrived), `partial` (part of it stands: a buy whose swap never happened after the account was funded, so the SOL is in the agent's Solana account, or a sale whose swap landed but whose transfer back did not finish, or that kept SOL, so the SOL is in the account or with 1Click until it refunds it; `solLeftLamports` says how much the account holds), `refunded` (1Click sent the funds back where they came from) or `failed` (nothing moved; `failureReason` says why). `denied` and `expired` mean the user denied it, or its approval ran out, before it started. `uncertain` means the result could not be confirmed yet: never ask the agent for a replacement, keep checking. `completed`, `partial`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the agent wallet or the Solana account did not hold enough, the account's reserve included. `quote_rejected`: the price or the route failed its checks, the loss limit would have been crossed, or a buy was under the minimum. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the approval no longer covered it, or the token is one the agent does not trade. `stopped`: an operator paused trading or turned the wallet off. `not_executed`: nothing it sent landed before it expired. `signing_disabled`: this deployment does not sign trades. In every case nothing moved." }, "stage": { "description": "The step it is on, once it started: `funding` moves USDC from the agent wallet to the Solana account as SOL through 1Click, `swap` trades on Jupiter, `sweep` sends a sale's SOL back to the agent wallet. A higher `revision` is newer.", "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1, "maximum": 1024, "description": "Persisted lifecycle stage number. Ignore an older snapshot for the same operation." }, "phase": { "type": "string", "enum": [ "funding", "swap", "sweep" ] }, "state": { "type": "string", "enum": [ "preparing", "prepared", "submitting", "pending", "delivering", "confirmed", "uncertain", "refunded", "failed", "not_executed" ] }, "transactionIndex": { "description": "The stored native transaction attempt, never a funding plan leg index.", "type": "integer", "minimum": 0, "maximum": 5 } }, "required": [ "revision", "phase", "state" ] }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "completeBy": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest it may still run, as the user signed it; its status is final by then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was placed." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When its records last changed." } }, "required": [ "id", "requestKey", "trade", "status", "failureReason", "transactions", "completeBy", "createdAt", "updatedAt" ], "description": "A Solana buy or sale the user placed themselves: its status, the step it is on, and what it paid and received." }, "SolanaTradeRequest": { "oneOf": [ { "type": "object", "properties": { "side": { "type": "string", "const": "buy", "description": "Buy the token." }, "buy": { "description": "The exact buy: the token, what it pays, its all-in loss bound and its SOL top-up cap.", "$ref": "#/components/schemas/SolanaBuyInput" } }, "required": [ "side", "buy" ] }, { "type": "object", "properties": { "side": { "type": "string", "const": "sell", "description": "Sell the token." }, "sell": { "description": "The exact sale: the token, how much of it, where the proceeds go and its all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" } }, "required": [ "side", "sell" ] } ], "description": "A buy or a sale of one Solana token through the agent's own Solana account." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Open a Solana account 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. `POST /v1/users/{userId}/solana/account` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/solana/account' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' ``` ## Responses ### 200 The user's Solana account. ```json { "description": "The user's Solana account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaAccount" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `solana_disabled` — Solana trading is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account ```json { "description": "The operation lost to the current state.\n\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.openAccount", "summary": "Open a Solana account", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's Solana account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaAccount" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `agent_wallet_required` — create the agent wallet before opening a perps, prediction-market or Solana account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "SolanaAccount": { "type": "object", "properties": { "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana address. Fin's policy service holds its key, which is not the agent wallet's." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the Solana account was first opened." }, "holdings": { "$ref": "#/components/schemas/SolanaHoldings" } }, "required": [ "address", "createdAt", "holdings" ], "description": "The agent's own Solana account and a live read of its SOL and recognized token balances." }, "SolanaHoldings": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "The account's balances and token recognition were read successfully." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the holdings were read." }, "sol": { "type": "object", "properties": { "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "All the SOL the account holds, in lamports." }, "reserveLamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "SOL the account always keeps for rent and network fees, so it can still sell and withdraw." }, "spendableLamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "SOL above the reserve, in lamports." }, "priceUsd": { "description": "The price of one SOL in US dollars; absent when it could not be read.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "valueUsd": { "description": "What the account's SOL is worth in US dollars; absent without a price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" } }, "required": [ "lamports", "reserveLamports", "spendableLamports" ], "description": "The account's SOL, which pays its network fees." }, "tokens": { "maxItems": 1000, "type": "array", "items": { "$ref": "#/components/schemas/SolanaTokenHolding" }, "description": "Recognized token balances: canonical wrapped SOL, tokens verified by the venue without a suspicious flag whose decimals and token program match the mint on chain, or tokens this account has a confirmed landed buy of. Recognition uses exact mints, never names, symbols or prices. Recognized tokens stay listed without a price." }, "valueUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "What the SOL and priced recognized tokens are worth together, in US dollars. Unpriced recognized holdings are left out and counted in `unpricedCount`; unrecognized tokens are excluded from both." }, "unpricedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many recognized holdings, SOL included, have no price and are left out of `valueUsd`. Unrecognized tokens are not counted." } }, "required": [ "status", "observedAt", "sol", "tokens", "valueUsd", "unpricedCount" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "The holdings could not be read." }, "reason": { "type": "string", "enum": [ "provider_unavailable", "invalid_response" ], "description": "Why the balances or evidence needed to recognize a held token could not be read. Never a zero balance or an empty token list." } }, "required": [ "status", "reason" ] } ], "description": "A live read of the Solana account's SOL and recognized token balances, or why it could not be read." }, "SolanaTokenHolding": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[0-9a-f]{64}$", "description": "The holding's stable id: `walletAssetId` of `solana:`." }, "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "symbol": { "description": "Its symbol, when the venue lists it.", "type": "string", "minLength": 1, "maxLength": 32 }, "name": { "description": "Its name, when the venue lists it.", "type": "string", "minLength": 1, "maxLength": 100 }, "iconUrl": { "type": "string", "pattern": "^\\/v1\\/solana\\/tokens\\/[1-9A-HJ-NP-Za-km-z]{32,44}\\/icon$", "description": "Where Fin serves the token's icon: the path of Get a token icon on this API, which answers the image, or not found when the data source's icon cannot be used. Absent when the data source lists none; draw a placeholder then." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "The mint's decimals." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint: `spl_token` (SPL Token) or `token_2022` (Token-2022)." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount held, in the token's smallest unit." }, "priceUsd": { "description": "The price of one whole token in US dollars; absent when it has no reliable price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "valueUsd": { "description": "What the holding is worth in US dollars; absent when it has no price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "averageCostUsd": { "description": "What the agent's own settled buys of the token paid for one whole token, in USDC, with each sale taking its share of the cost: an average cost, never a market price. Absent when no buy paid in USDC can state one, as when a buy was paid in SOL.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "unrealizedPnlUsd": { "description": "What the holding has gained (positive) or lost (negative) against that average cost at `priceUsd`, in US dollars: (`priceUsd` − `averageCostUsd`) × the amount held. Absent without both.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "costBasisStatus": { "description": "How far `averageCostUsd` can be trusted. `complete`: every buy and sell of the token the agent made settled with its amounts recorded, every buy was paid in USDC, and those trades account for exactly the amount held. `partial`: one of them is still in flight or left an amount unknown, a buy was paid in SOL, or the amount held moved outside those trades, so say so wherever the average is shown. `unknown`: the agent has no settled buy of it, so there is no average cost.", "type": "string", "enum": [ "complete", "partial", "unknown" ] } }, "required": [ "assetId", "mint", "decimals", "tokenProgram", "amountRaw" ], "description": "One recognized token the Solana account holds; it stays listed when it has no price." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a Solana account 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. `GET /v1/users/{userId}/solana/account` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/solana/account' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The user's Solana account and what it holds now. ```json { "description": "The user's Solana account and what it holds now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaAccount" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. - `no_account` — the user has not opened the account this call reads; open it first ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.getAccount", "summary": "Get a Solana account", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's Solana account and what it holds now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaAccount" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "SolanaAccount": { "type": "object", "properties": { "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana address. Fin's policy service holds its key, which is not the agent wallet's." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the Solana account was first opened." }, "holdings": { "$ref": "#/components/schemas/SolanaHoldings" } }, "required": [ "address", "createdAt", "holdings" ], "description": "The agent's own Solana account and a live read of its SOL and recognized token balances." }, "SolanaHoldings": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "The account's balances and token recognition were read successfully." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the holdings were read." }, "sol": { "type": "object", "properties": { "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "All the SOL the account holds, in lamports." }, "reserveLamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "SOL the account always keeps for rent and network fees, so it can still sell and withdraw." }, "spendableLamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "SOL above the reserve, in lamports." }, "priceUsd": { "description": "The price of one SOL in US dollars; absent when it could not be read.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "valueUsd": { "description": "What the account's SOL is worth in US dollars; absent without a price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" } }, "required": [ "lamports", "reserveLamports", "spendableLamports" ], "description": "The account's SOL, which pays its network fees." }, "tokens": { "maxItems": 1000, "type": "array", "items": { "$ref": "#/components/schemas/SolanaTokenHolding" }, "description": "Recognized token balances: canonical wrapped SOL, tokens verified by the venue without a suspicious flag whose decimals and token program match the mint on chain, or tokens this account has a confirmed landed buy of. Recognition uses exact mints, never names, symbols or prices. Recognized tokens stay listed without a price." }, "valueUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "What the SOL and priced recognized tokens are worth together, in US dollars. Unpriced recognized holdings are left out and counted in `unpricedCount`; unrecognized tokens are excluded from both." }, "unpricedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many recognized holdings, SOL included, have no price and are left out of `valueUsd`. Unrecognized tokens are not counted." } }, "required": [ "status", "observedAt", "sol", "tokens", "valueUsd", "unpricedCount" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "The holdings could not be read." }, "reason": { "type": "string", "enum": [ "provider_unavailable", "invalid_response" ], "description": "Why the balances or evidence needed to recognize a held token could not be read. Never a zero balance or an empty token list." } }, "required": [ "status", "reason" ] } ], "description": "A live read of the Solana account's SOL and recognized token balances, or why it could not be read." }, "SolanaTokenHolding": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[0-9a-f]{64}$", "description": "The holding's stable id: `walletAssetId` of `solana:`." }, "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "symbol": { "description": "Its symbol, when the venue lists it.", "type": "string", "minLength": 1, "maxLength": 32 }, "name": { "description": "Its name, when the venue lists it.", "type": "string", "minLength": 1, "maxLength": 100 }, "iconUrl": { "type": "string", "pattern": "^\\/v1\\/solana\\/tokens\\/[1-9A-HJ-NP-Za-km-z]{32,44}\\/icon$", "description": "Where Fin serves the token's icon: the path of Get a token icon on this API, which answers the image, or not found when the data source's icon cannot be used. Absent when the data source lists none; draw a placeholder then." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "The mint's decimals." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint: `spl_token` (SPL Token) or `token_2022` (Token-2022)." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount held, in the token's smallest unit." }, "priceUsd": { "description": "The price of one whole token in US dollars; absent when it has no reliable price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "valueUsd": { "description": "What the holding is worth in US dollars; absent when it has no price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "averageCostUsd": { "description": "What the agent's own settled buys of the token paid for one whole token, in USDC, with each sale taking its share of the cost: an average cost, never a market price. Absent when no buy paid in USDC can state one, as when a buy was paid in SOL.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "unrealizedPnlUsd": { "description": "What the holding has gained (positive) or lost (negative) against that average cost at `priceUsd`, in US dollars: (`priceUsd` − `averageCostUsd`) × the amount held. Absent without both.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "costBasisStatus": { "description": "How far `averageCostUsd` can be trusted. `complete`: every buy and sell of the token the agent made settled with its amounts recorded, every buy was paid in USDC, and those trades account for exactly the amount held. `partial`: one of them is still in flight or left an amount unknown, a buy was paid in SOL, or the amount held moved outside those trades, so say so wherever the average is shown. `unknown`: the agent has no settled buy of it, so there is no average cost.", "type": "string", "enum": [ "complete", "partial", "unknown" ] } }, "required": [ "assetId", "mint", "decimals", "tokenProgram", "amountRaw" ], "description": "One recognized token the Solana account holds; it stays listed when it has no price." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Search Solana tokens 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. `GET /v1/solana/tokens/search` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Query parameters ```json [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "query", "name": "query", "required": true, "description": "A ticker, a name or a pasted mint address. A leading `$` is ignored." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/solana/tokens/search?query=YOUR_QUERY' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The candidates for the query, best first. ```json { "description": "The candidates for the query, best first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenSearch" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `solana_disabled` — Solana trading is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.searchTokens", "summary": "Search Solana tokens", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "query", "name": "query", "required": true, "description": "A ticker, a name or a pasted mint address. A leading `$` is ignored." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The candidates for the query, best first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenSearch" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "SolanaTokenSearch": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 128, "description": "What was searched for, as normalized." }, "ambiguous": { "type": "boolean", "description": "True when the query does not name one token: several candidates share the top symbol. Show them and ask; never pick by symbol alone." }, "source": { "type": "object", "properties": { "name": { "type": "string", "const": "Jupiter", "description": "Who the market data comes from." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was read." } }, "required": [ "name", "observedAt" ], "description": "Where the market data comes from and when it was read." }, "items": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/SolanaTokenSummary" }, "description": "The candidates, best match first; a pasted mint answers that mint alone." } }, "required": [ "query", "ambiguous", "source", "items" ], "description": "Solana tokens matching a ticker, a name or a pasted mint." }, "SolanaTokenSummary": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address: its only unambiguous identity, since symbols are not unique." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 32, "description": "The token's symbol as the venue lists it." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The token's name as the venue lists it." }, "iconUrl": { "type": "string", "pattern": "^\\/v1\\/solana\\/tokens\\/[1-9A-HJ-NP-Za-km-z]{32,44}\\/icon$", "description": "Where Fin serves the token's icon: the path of Get a token icon on this API, which answers the image, or not found when the data source's icon cannot be used. Absent when the data source lists none; draw a placeholder then." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "The mint's decimals." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint: `spl_token` (SPL Token) or `token_2022` (Token-2022)." }, "priceUsd": { "description": "The price of one whole token in US dollars; absent when it has no reliable price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "priceChange24hPct": { "description": "The price change over 24 hours, in percent.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "liquidityUsd": { "description": "Liquidity across the token's pools, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "mcapUsd": { "description": "Market capitalization, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "createdAt": { "description": "When the token was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "launchpad": { "description": "The launchpad that created it, such as `pump.fun`.", "type": "string", "minLength": 1, "maxLength": 64 }, "graduated": { "description": "True once it left its launchpad's bonding curve for an open pool.", "type": "boolean" }, "verified": { "description": "True when the venue lists it as verified.", "type": "boolean" }, "organicScoreLabel": { "description": "How much of its activity the venue judges organic rather than bot-driven.", "type": "string", "enum": [ "high", "medium", "low" ] }, "membership": { "$ref": "#/components/schemas/SolanaTokenMembership" }, "firstPoolAt": { "description": "When its first liquidity pool opened; distinct from mint creation.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "discoveredAt": { "description": "When Fin first recorded the token.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "marketObservedAt": { "description": "The market provider's own update time, or the successful read time when it supplies none.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "assessmentObservedAt": { "description": "When the current on-chain mint assessment was made.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "holders": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicScore": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "topHoldersPct": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "dataGaps": { "description": "Important evidence that is missing or too old; absence is never a zero value.", "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "research": { "$ref": "#/components/schemas/SolanaTokenResearch" }, "stats": { "type": "object", "properties": { "5m": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." }, "1h": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." }, "6h": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." }, "24h": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." } }, "description": "Trading activity by window; a window is absent when the venue has none for it." }, "risk": { "$ref": "#/components/schemas/SolanaRisk" }, "tradable": { "type": "boolean", "description": "Whether Fin would buy it now: priced, with a risk that is neither `blocked` nor `unknown`, at most 18 decimals, and not wrapped SOL, which a buy pays with. Never propose a buy of an untradable token." } }, "required": [ "mint", "symbol", "name", "decimals", "tokenProgram", "stats", "risk", "tradable" ], "description": "One Solana token: its identity, market data and risk verdict." }, "SolanaTokenMembership": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "meme", "launch_candidate", "other", "unknown" ], "description": "Confirmed meme membership, a launch awaiting classification, another token category, or insufficient classification evidence." }, "basis": { "type": "string", "enum": [ "coingecko_category", "jupiter_tag", "reviewed_mint", "launchpad", "none" ], "description": "The evidence used for classification. A name or symbol alone is never classification evidence." }, "observedAt": { "description": "When the classification evidence was obtained.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "kind", "basis" ] }, "SolanaTokenResearch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "limited", "unavailable" ], "description": "Whether the available observations support comparative research; not a safety rating or recommendation." }, "availableWindows": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "5m", "1h", "6h", "24h" ], "description": "A trailing window: the last 5 minutes, hour, 6 hours or 24 hours." } }, "missing": { "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "price", "liquidity", "activity", "participants", "organic_activity", "concentration", "mint", "freshness" ] }, "description": "Evidence absent or too old to support the corresponding claim." } }, "required": [ "status", "availableWindows", "missing" ] }, "SolanaRisk": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "blocked", "high", "medium", "low", "unknown" ], "description": "The overall verdict: `blocked` has a hard flag and is never bought; `unknown` when the mint could not be read, which also blocks a buy, since a mint no one has read never passes; `high` with two or more of `low_liquidity`, `new_token`, `top_holders`, `suspicious`, `unverified` and `low_organic`, `medium` with one, `low` with none. Never a statement that a token is safe." }, "hard": { "maxItems": 19, "type": "array", "items": { "type": "string", "enum": [ "freeze_authority", "transfer_hook", "permanent_delegate", "non_transferable", "default_frozen", "transfer_fee", "pausable", "unknown_extension", "not_sellable", "mint_authority", "hook_authority", "low_liquidity", "new_token", "top_holders", "unverified", "low_organic", "suspicious", "promoted", "unpriced" ] }, "description": "Facts that refuse a buy: `freeze_authority` (the creator can freeze holdings), `transfer_hook` (every transfer runs the creator's program), `permanent_delegate` (someone can move or burn any holding), `non_transferable`, `default_frozen` (new holdings start frozen), `transfer_fee` (transfers pay a fee, or someone can set one), `pausable` (someone can pause every transfer, or has), `unknown_extension` (a Token-2022 extension Fin has not reviewed) and `not_sellable`." }, "soft": { "maxItems": 19, "type": "array", "items": { "type": "string", "enum": [ "freeze_authority", "transfer_hook", "permanent_delegate", "non_transferable", "default_frozen", "transfer_fee", "pausable", "unknown_extension", "not_sellable", "mint_authority", "hook_authority", "low_liquidity", "new_token", "top_holders", "unverified", "low_organic", "suspicious", "promoted", "unpriced" ] }, "description": "Warnings to show beside the token, such as `mint_authority` (more can be created) and `hook_authority` (the issuer can add a transfer rule later). `new_token` warns that the mint or its first trading pool is less than a day old; their timestamps remain distinct. Only `unpriced` stops a buy, because a buy's loss cannot be bounded without a price." } }, "required": [ "level", "hard", "soft" ], "description": "Fin's risk verdict on a Solana token, from its mint facts and the venue's data." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List Solana tokens 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. `GET /v1/solana/tokens` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Query parameters ```json [ { "schema": { "default": "trending", "type": "string", "enum": [ "trending", "traded", "organic", "new", "gainers" ] }, "in": "query", "name": "lane", "required": false, "description": "How to rank observed candidates: organic volume, volume, organic score, newest pools or price gain. Defaults to `trending`." }, { "schema": { "default": "1h", "type": "string", "enum": [ "5m", "1h", "6h", "24h" ] }, "in": "query", "name": "interval", "required": false, "description": "The trailing window the list ranks by: 5m, 1h, 6h or 24h. Defaults to 1h." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 25 }, "in": "query", "name": "limit", "required": false, "description": "How many tokens to list, at most 25. Defaults to 10." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "in": "query", "name": "cursor", "required": false, "description": "The nextCursor from the previous page with these same filters." }, { "schema": { "type": "string", "enum": [ "meme", "launches", "all" ] }, "in": "query", "name": "membership", "required": false, "description": "Confirmed memes, recent launch candidates, or all sampled tokens. Defaults to memes, except the new lane defaults to launches." }, { "schema": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "in": "query", "name": "minLiquidityUsd", "required": false, "description": "Minimum pool liquidity in US dollars; no minimum unless supplied." }, { "schema": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "in": "query", "name": "maxLiquidityUsd", "required": false, "description": "Maximum pool liquidity in US dollars." }, { "schema": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "in": "query", "name": "minMarketCapUsd", "required": false, "description": "Minimum reported market capitalization in US dollars; FDV is not substituted." }, { "schema": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "in": "query", "name": "maxMarketCapUsd", "required": false, "description": "Maximum reported market capitalization in US dollars." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 87600 }, "in": "query", "name": "maxAgeHours", "required": false, "description": "Maximum hours since the first pool opened; missing pool age does not match." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "launchpad", "required": false, "description": "A launchpad name reported by the source." }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "tradableOnly", "required": false, "description": "Limit results to tokens the current mint and price reads permit buying. Defaults to false." }, { "schema": { "type": "string", "enum": [ "rank", "liquidity", "market_cap", "age", "change", "move" ] }, "in": "query", "name": "sort", "required": false, "description": "Order by ranking, liquidity, capitalization, age, window price change, or `move`: the size of that change, up or down, largest first." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "direction", "required": false, "description": "The selected sort direction; defaults follow the selected ranking." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/solana/tokens' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The ranked tokens of the lane. ```json { "description": "The ranked tokens of the lane.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenList" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `solana_disabled` — Solana trading is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.listTokens", "summary": "List Solana tokens", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "default": "trending", "type": "string", "enum": [ "trending", "traded", "organic", "new", "gainers" ] }, "in": "query", "name": "lane", "required": false, "description": "How to rank observed candidates: organic volume, volume, organic score, newest pools or price gain. Defaults to `trending`." }, { "schema": { "default": "1h", "type": "string", "enum": [ "5m", "1h", "6h", "24h" ] }, "in": "query", "name": "interval", "required": false, "description": "The trailing window the list ranks by: 5m, 1h, 6h or 24h. Defaults to 1h." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 25 }, "in": "query", "name": "limit", "required": false, "description": "How many tokens to list, at most 25. Defaults to 10." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "in": "query", "name": "cursor", "required": false, "description": "The nextCursor from the previous page with these same filters." }, { "schema": { "type": "string", "enum": [ "meme", "launches", "all" ] }, "in": "query", "name": "membership", "required": false, "description": "Confirmed memes, recent launch candidates, or all sampled tokens. Defaults to memes, except the new lane defaults to launches." }, { "schema": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "in": "query", "name": "minLiquidityUsd", "required": false, "description": "Minimum pool liquidity in US dollars; no minimum unless supplied." }, { "schema": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "in": "query", "name": "maxLiquidityUsd", "required": false, "description": "Maximum pool liquidity in US dollars." }, { "schema": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "in": "query", "name": "minMarketCapUsd", "required": false, "description": "Minimum reported market capitalization in US dollars; FDV is not substituted." }, { "schema": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "in": "query", "name": "maxMarketCapUsd", "required": false, "description": "Maximum reported market capitalization in US dollars." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 87600 }, "in": "query", "name": "maxAgeHours", "required": false, "description": "Maximum hours since the first pool opened; missing pool age does not match." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "launchpad", "required": false, "description": "A launchpad name reported by the source." }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "tradableOnly", "required": false, "description": "Limit results to tokens the current mint and price reads permit buying. Defaults to false." }, { "schema": { "type": "string", "enum": [ "rank", "liquidity", "market_cap", "age", "change", "move" ] }, "in": "query", "name": "sort", "required": false, "description": "Order by ranking, liquidity, capitalization, age, window price change, or `move`: the size of that change, up or down, largest first." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "direction", "required": false, "description": "The selected sort direction; defaults follow the selected ranking." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The ranked tokens of the lane.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenList" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "SolanaTokenList": { "type": "object", "properties": { "lane": { "type": "string", "enum": [ "trending", "traded", "organic", "new", "gainers" ], "description": "Which ranking: organic trading volume, total volume, organic activity, newest pools or price gain. Ranking describes observed activity, not expected returns." }, "interval": { "type": "string", "enum": [ "5m", "1h", "6h", "24h" ], "description": "The window the list ranks by." }, "source": { "type": "object", "properties": { "name": { "type": "string", "const": "Jupiter", "description": "Who the market data comes from." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was read." } }, "required": [ "name", "observedAt" ], "description": "Where the market data comes from and when it was read." }, "status": { "type": "string", "enum": [ "ready", "stale", "unavailable" ] }, "asOf": { "description": "When this discovery snapshot was selected.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "snapshotId": { "description": "The fixed catalog revision used by every page of this result.", "type": "string", "minLength": 1, "maxLength": 120 }, "nextCursor": { "description": "Pass this cursor with the same filters for the next page; null means this snapshot has no more matches.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048 }, { "type": "null" } ] }, "coverage": { "type": "object", "properties": { "universe": { "type": "string", "const": "sampled", "description": "Discovery samples provider feeds and does not claim every token on Solana." }, "observedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eligibleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "returnedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limitReached": { "type": "boolean", "description": "True when a configured collection or scan limit narrowed coverage." }, "sources": { "maxItems": 32, "type": "array", "items": { "$ref": "#/components/schemas/SolanaDiscoverySourceCoverage" } } }, "required": [ "universe", "observedCount", "eligibleCount", "returnedCount", "limitReached", "sources" ] }, "items": { "maxItems": 25, "type": "array", "items": { "$ref": "#/components/schemas/SolanaTokenListItem" }, "description": "The ranked tokens, in rank order, after the list's quality gates." } }, "required": [ "lane", "interval", "source", "items" ], "description": "A ranked list of Solana tokens in one lane and window." }, "SolanaDiscoverySourceCoverage": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The sampled source or feed." }, "provider": { "type": "string", "enum": [ "Jupiter", "CoinGecko", "GeckoTerminal" ] }, "status": { "type": "string", "enum": [ "ready", "stale", "unavailable", "pending" ] }, "observedAt": { "description": "When the last successful source read completed.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "reason": { "description": "Why source coverage is incomplete.", "type": "string", "minLength": 1, "maxLength": 200 }, "count": { "description": "The number of candidates in the last successful source read.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "status" ] }, "SolanaTokenListItem": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Its place in the sampled snapshot, from 1." }, "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address: its only unambiguous identity, since symbols are not unique." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 32, "description": "The token's symbol as the venue lists it." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The token's name as the venue lists it." }, "iconUrl": { "type": "string", "pattern": "^\\/v1\\/solana\\/tokens\\/[1-9A-HJ-NP-Za-km-z]{32,44}\\/icon$", "description": "Where Fin serves the token's icon: the path of Get a token icon on this API, which answers the image, or not found when the data source's icon cannot be used. Absent when the data source lists none; draw a placeholder then." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "The mint's decimals." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint: `spl_token` (SPL Token) or `token_2022` (Token-2022)." }, "priceUsd": { "description": "The price of one whole token in US dollars; absent when it has no reliable price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "priceChange24hPct": { "description": "The price change over 24 hours, in percent.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "liquidityUsd": { "description": "Liquidity across the token's pools, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "mcapUsd": { "description": "Market capitalization, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "createdAt": { "description": "When the token was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "launchpad": { "description": "The launchpad that created it, such as `pump.fun`.", "type": "string", "minLength": 1, "maxLength": 64 }, "graduated": { "description": "True once it left its launchpad's bonding curve for an open pool.", "type": "boolean" }, "verified": { "description": "True when the venue lists it as verified.", "type": "boolean" }, "organicScoreLabel": { "description": "How much of its activity the venue judges organic rather than bot-driven.", "type": "string", "enum": [ "high", "medium", "low" ] }, "membership": { "$ref": "#/components/schemas/SolanaTokenMembership" }, "firstPoolAt": { "description": "When its first liquidity pool opened; distinct from mint creation.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "discoveredAt": { "description": "When Fin first recorded the token.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "marketObservedAt": { "description": "The market provider's own update time, or the successful read time when it supplies none.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "assessmentObservedAt": { "description": "When the current on-chain mint assessment was made.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "holders": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicScore": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "topHoldersPct": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "dataGaps": { "description": "Important evidence that is missing or too old; absence is never a zero value.", "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "research": { "$ref": "#/components/schemas/SolanaTokenResearch" }, "stats": { "type": "object", "properties": { "5m": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." }, "1h": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." }, "6h": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." }, "24h": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." } }, "description": "Trading activity by window; a window is absent when the venue has none for it." }, "risk": { "$ref": "#/components/schemas/SolanaRisk" }, "tradable": { "type": "boolean", "description": "Whether Fin would buy it now: priced, with a risk that is neither `blocked` nor `unknown`, at most 18 decimals, and not wrapped SOL, which a buy pays with. Never propose a buy of an untradable token." }, "reason": { "type": "string", "minLength": 1, "maxLength": 200, "description": "One line on why it is listed, such as its organic volume and traders in the window." } }, "required": [ "rank", "mint", "symbol", "name", "decimals", "tokenProgram", "stats", "risk", "tradable", "reason" ], "description": "One ranked token in a list." }, "SolanaTokenMembership": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "meme", "launch_candidate", "other", "unknown" ], "description": "Confirmed meme membership, a launch awaiting classification, another token category, or insufficient classification evidence." }, "basis": { "type": "string", "enum": [ "coingecko_category", "jupiter_tag", "reviewed_mint", "launchpad", "none" ], "description": "The evidence used for classification. A name or symbol alone is never classification evidence." }, "observedAt": { "description": "When the classification evidence was obtained.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "kind", "basis" ] }, "SolanaTokenResearch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "limited", "unavailable" ], "description": "Whether the available observations support comparative research; not a safety rating or recommendation." }, "availableWindows": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "5m", "1h", "6h", "24h" ], "description": "A trailing window: the last 5 minutes, hour, 6 hours or 24 hours." } }, "missing": { "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "price", "liquidity", "activity", "participants", "organic_activity", "concentration", "mint", "freshness" ] }, "description": "Evidence absent or too old to support the corresponding claim." } }, "required": [ "status", "availableWindows", "missing" ] }, "SolanaRisk": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "blocked", "high", "medium", "low", "unknown" ], "description": "The overall verdict: `blocked` has a hard flag and is never bought; `unknown` when the mint could not be read, which also blocks a buy, since a mint no one has read never passes; `high` with two or more of `low_liquidity`, `new_token`, `top_holders`, `suspicious`, `unverified` and `low_organic`, `medium` with one, `low` with none. Never a statement that a token is safe." }, "hard": { "maxItems": 19, "type": "array", "items": { "type": "string", "enum": [ "freeze_authority", "transfer_hook", "permanent_delegate", "non_transferable", "default_frozen", "transfer_fee", "pausable", "unknown_extension", "not_sellable", "mint_authority", "hook_authority", "low_liquidity", "new_token", "top_holders", "unverified", "low_organic", "suspicious", "promoted", "unpriced" ] }, "description": "Facts that refuse a buy: `freeze_authority` (the creator can freeze holdings), `transfer_hook` (every transfer runs the creator's program), `permanent_delegate` (someone can move or burn any holding), `non_transferable`, `default_frozen` (new holdings start frozen), `transfer_fee` (transfers pay a fee, or someone can set one), `pausable` (someone can pause every transfer, or has), `unknown_extension` (a Token-2022 extension Fin has not reviewed) and `not_sellable`." }, "soft": { "maxItems": 19, "type": "array", "items": { "type": "string", "enum": [ "freeze_authority", "transfer_hook", "permanent_delegate", "non_transferable", "default_frozen", "transfer_fee", "pausable", "unknown_extension", "not_sellable", "mint_authority", "hook_authority", "low_liquidity", "new_token", "top_holders", "unverified", "low_organic", "suspicious", "promoted", "unpriced" ] }, "description": "Warnings to show beside the token, such as `mint_authority` (more can be created) and `hook_authority` (the issuer can add a transfer rule later). `new_token` warns that the mint or its first trading pool is less than a day old; their timestamps remain distinct. Only `unpriced` stops a buy, because a buy's loss cannot be bounded without a price." } }, "required": [ "level", "hard", "soft" ], "description": "Fin's risk verdict on a Solana token, from its mint facts and the venue's data." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List token sparklines 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. `GET /v1/solana/tokens/sparklines` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Query parameters ```json [ { "schema": { "default": "1h", "type": "string", "enum": [ "1h", "6h", "24h" ] }, "in": "query", "name": "interval", "required": false, "description": "How far back each line goes: 1h, 6h or 24h. Defaults to 1h." }, { "schema": { "anyOf": [ { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana address: base58 text of a 32-byte public key." }, { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana address: base58 text of a 32-byte public key." } } ] }, "in": "query", "name": "mint", "required": true, "description": "The tokens' mint addresses, one `mint` for each, at most 25." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/solana/tokens/sparklines?mint=YOUR_MINT' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 Each token's line, or why it has none. ```json { "description": "Each token's line, or why it has none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenSparklines" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `solana_disabled` — Solana trading is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.listTokenSparklines", "summary": "List token sparklines", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "default": "1h", "type": "string", "enum": [ "1h", "6h", "24h" ] }, "in": "query", "name": "interval", "required": false, "description": "How far back each line goes: 1h, 6h or 24h. Defaults to 1h." }, { "schema": { "anyOf": [ { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana address: base58 text of a 32-byte public key." }, { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana address: base58 text of a 32-byte public key." } } ] }, "in": "query", "name": "mint", "required": true, "description": "The tokens' mint addresses, one `mint` for each, at most 25." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "Each token's line, or why it has none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenSparklines" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "SolanaTokenSparklines": { "type": "object", "properties": { "interval": { "type": "string", "enum": [ "1h", "6h", "24h" ], "description": "How far back the line goes: the last hour, 6 hours or 24 hours." }, "source": { "type": "object", "properties": { "name": { "type": "string", "const": "Jupiter", "description": "Who the market data comes from." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was read." } }, "required": [ "name", "observedAt" ], "description": "Where the market data comes from and when it was read." }, "items": { "maxItems": 25, "type": "array", "items": { "$ref": "#/components/schemas/SolanaTokenSparkline" }, "description": "Each token asked for, once, in the order asked." } }, "required": [ "interval", "source", "items" ], "description": "Small price lines for several tokens over one window." }, "SolanaTokenSparkline": { "oneOf": [ { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "status": { "type": "string", "const": "observed", "description": "Fin sampled enough of the window to draw it." }, "points": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin read this price." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The price of one whole token in US dollars." } }, "required": [ "time", "priceUsd" ] }, "description": "The sampled prices, oldest first." } }, "required": [ "mint", "status", "points" ] }, { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "status": { "type": "string", "const": "unavailable", "description": "There is no line to draw." }, "reason": { "type": "string", "enum": [ "not_sampled", "too_sparse" ], "description": "`not_sampled` when Fin read no price for it in the window; `too_sparse` when what it read would draw a misleading line: too few prices, a late start or a long gap." } }, "required": [ "mint", "status", "reason" ] } ], "description": "One token's price line over the window, or why it has none." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List token launch status 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 /v1/solana/tokens/launch-status` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Query parameters ```json [ { "schema": { "anyOf": [ { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana address: base58 text of a 32-byte public key." }, { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana address: base58 text of a 32-byte public key." } } ] }, "in": "query", "name": "mint", "required": true, "description": "The tokens' mint addresses, one `mint` for each, at most 25." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/solana/tokens/launch-status?mint=YOUR_MINT' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 Where each token stands on its launchpad. ```json { "description": "Where each token stands on its launchpad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenLaunchStatus" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `solana_disabled` — Solana trading is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.listTokenLaunchStatus", "summary": "List token launch status", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "anyOf": [ { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana address: base58 text of a 32-byte public key." }, { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana address: base58 text of a 32-byte public key." } } ] }, "in": "query", "name": "mint", "required": true, "description": "The tokens' mint addresses, one `mint` for each, at most 25." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "Where each token stands on its launchpad.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenLaunchStatus" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "SolanaTokenLaunchStatus": { "type": "object", "properties": { "items": { "maxItems": 25, "type": "array", "items": { "$ref": "#/components/schemas/SolanaTokenLaunchItem" }, "description": "Each token asked for, once, in the order asked." } }, "required": [ "items" ], "description": "Where several tokens stand on their launchpads." }, "SolanaTokenLaunchItem": { "oneOf": [ { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "status": { "type": "string", "const": "curve", "description": "It is on its launchpad's bonding curve." }, "launchpad": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The launchpad: `pump.fun`." }, "progressPct": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "How much of what the curve sells has been bought, in percent, cut to two decimals: `5.50`." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the curve was read from the chain." } }, "required": [ "mint", "status", "launchpad", "progressPct", "observedAt" ] }, { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "status": { "type": "string", "const": "graduated", "description": "It left its launchpad's curve for an open pool." }, "launchpad": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The launchpad it left, as the venue names it, such as `pump.fun`." }, "graduatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it left, as the venue states it." } }, "required": [ "mint", "status", "launchpad", "graduatedAt" ] }, { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "status": { "type": "string", "const": "unknown", "description": "Fin cannot say: no launchpad is named for it, its launchpad's curve is not one Fin reads, or the chain or the venue could not be read just now." } }, "required": [ "mint", "status" ] } ], "description": "Where one token stands on its launchpad." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a Solana token 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 /v1/solana/tokens/{mint}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "in": "path", "name": "mint", "required": true, "description": "The token's mint address. Symbols are not unique, so find the mint with Search Solana tokens." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/solana/tokens/YOUR_MINT' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The token and Fin's verdict on it. ```json { "description": "The token and Fin's verdict on it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenDetail" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.getToken", "summary": "Get a Solana token", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "in": "path", "name": "mint", "required": true, "description": "The token's mint address. Symbols are not unique, so find the mint with Search Solana tokens." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The token and Fin's verdict on it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenDetail" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "SolanaTokenDetail": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address: its only unambiguous identity, since symbols are not unique." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 32, "description": "The token's symbol as the venue lists it." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The token's name as the venue lists it." }, "iconUrl": { "type": "string", "pattern": "^\\/v1\\/solana\\/tokens\\/[1-9A-HJ-NP-Za-km-z]{32,44}\\/icon$", "description": "Where Fin serves the token's icon: the path of Get a token icon on this API, which answers the image, or not found when the data source's icon cannot be used. Absent when the data source lists none; draw a placeholder then." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "The mint's decimals." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint: `spl_token` (SPL Token) or `token_2022` (Token-2022)." }, "priceUsd": { "description": "The price of one whole token in US dollars; absent when it has no reliable price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "priceChange24hPct": { "description": "The price change over 24 hours, in percent.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "liquidityUsd": { "description": "Liquidity across the token's pools, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "mcapUsd": { "description": "Market capitalization, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "createdAt": { "description": "When the token was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "launchpad": { "description": "The launchpad that created it, such as `pump.fun`.", "type": "string", "minLength": 1, "maxLength": 64 }, "graduated": { "description": "True once it left its launchpad's bonding curve for an open pool.", "type": "boolean" }, "verified": { "description": "True when the venue lists it as verified.", "type": "boolean" }, "organicScoreLabel": { "description": "How much of its activity the venue judges organic rather than bot-driven.", "type": "string", "enum": [ "high", "medium", "low" ] }, "membership": { "$ref": "#/components/schemas/SolanaTokenMembership" }, "firstPoolAt": { "description": "When its first liquidity pool opened; distinct from mint creation.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "discoveredAt": { "description": "When Fin first recorded the token.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "marketObservedAt": { "description": "The market provider's own update time, or the successful read time when it supplies none.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "assessmentObservedAt": { "description": "When the current on-chain mint assessment was made.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "holders": { "description": "How many wallets hold it.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicScore": { "description": "The venue's organic score, 0 to 100: how much of its trading comes from real wallets rather than bots.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "topHoldersPct": { "description": "The share of the supply its largest holders hold, in percent, as the venue counts them: how much a few wallets selling could move the price.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "dataGaps": { "description": "Important evidence that is missing or too old; absence is never a zero value.", "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "research": { "$ref": "#/components/schemas/SolanaTokenResearch" }, "stats": { "type": "object", "properties": { "5m": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." }, "1h": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." }, "6h": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." }, "24h": { "type": "object", "properties": { "volumeUsd": { "description": "Traded volume in the window, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "organicVolumeUsd": { "description": "The part of that volume the venue judges organic, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "buyVolumeUsd": { "description": "What buyers paid in the window, in US dollars: the buying side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "sellVolumeUsd": { "description": "What sellers received in the window, in US dollars: the selling side of the volume.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "traders": { "description": "Distinct wallets that bought or sold in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyers": { "description": "Distinct buying wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellers": { "description": "Distinct selling wallets in the window.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buys": { "description": "Buy transactions in the window; not distinct buyers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sells": { "description": "Sell transactions in the window; not distinct sellers.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organicBuyers": { "description": "Organic wallets that were net buyers in the window, as counted by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "netBuyers": { "description": "Net-buying wallets in the window, as reported by the venue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "priceChangePct": { "description": "The price change over the window, in percent: `-12.5` is down 12.5%.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "description": "Trading activity in one window; each figure absent when the venue has none." } }, "description": "Trading activity by window; a window is absent when the venue has none for it." }, "risk": { "$ref": "#/components/schemas/SolanaRisk" }, "tradable": { "type": "boolean", "description": "Whether Fin would buy it now: priced, with a risk that is neither `blocked` nor `unknown`, at most 18 decimals, and not wrapped SOL, which a buy pays with. Never propose a buy of an untradable token." }, "fdvUsd": { "description": "Fully diluted valuation, in US dollars.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "creatorHoldsPct": { "description": "The share of the supply the wallet that created it holds, in percent.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "bondingProgressPct": { "description": "How far along its launchpad's bonding curve it is, in percent, before it graduates.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "links": { "$ref": "#/components/schemas/SolanaTokenLinks" }, "source": { "type": "object", "properties": { "name": { "type": "string", "const": "Jupiter", "description": "Who the market data comes from." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was read." } }, "required": [ "name", "observedAt" ], "description": "Where the market data comes from and when it was read." } }, "required": [ "mint", "symbol", "name", "decimals", "tokenProgram", "stats", "risk", "tradable", "source" ], "description": "One Solana token in full: identity, market data, activity and risk verdict." }, "SolanaTokenMembership": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "meme", "launch_candidate", "other", "unknown" ], "description": "Confirmed meme membership, a launch awaiting classification, another token category, or insufficient classification evidence." }, "basis": { "type": "string", "enum": [ "coingecko_category", "jupiter_tag", "reviewed_mint", "launchpad", "none" ], "description": "The evidence used for classification. A name or symbol alone is never classification evidence." }, "observedAt": { "description": "When the classification evidence was obtained.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "kind", "basis" ] }, "SolanaTokenResearch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "limited", "unavailable" ], "description": "Whether the available observations support comparative research; not a safety rating or recommendation." }, "availableWindows": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "5m", "1h", "6h", "24h" ], "description": "A trailing window: the last 5 minutes, hour, 6 hours or 24 hours." } }, "missing": { "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "price", "liquidity", "activity", "participants", "organic_activity", "concentration", "mint", "freshness" ] }, "description": "Evidence absent or too old to support the corresponding claim." } }, "required": [ "status", "availableWindows", "missing" ] }, "SolanaRisk": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "blocked", "high", "medium", "low", "unknown" ], "description": "The overall verdict: `blocked` has a hard flag and is never bought; `unknown` when the mint could not be read, which also blocks a buy, since a mint no one has read never passes; `high` with two or more of `low_liquidity`, `new_token`, `top_holders`, `suspicious`, `unverified` and `low_organic`, `medium` with one, `low` with none. Never a statement that a token is safe." }, "hard": { "maxItems": 19, "type": "array", "items": { "type": "string", "enum": [ "freeze_authority", "transfer_hook", "permanent_delegate", "non_transferable", "default_frozen", "transfer_fee", "pausable", "unknown_extension", "not_sellable", "mint_authority", "hook_authority", "low_liquidity", "new_token", "top_holders", "unverified", "low_organic", "suspicious", "promoted", "unpriced" ] }, "description": "Facts that refuse a buy: `freeze_authority` (the creator can freeze holdings), `transfer_hook` (every transfer runs the creator's program), `permanent_delegate` (someone can move or burn any holding), `non_transferable`, `default_frozen` (new holdings start frozen), `transfer_fee` (transfers pay a fee, or someone can set one), `pausable` (someone can pause every transfer, or has), `unknown_extension` (a Token-2022 extension Fin has not reviewed) and `not_sellable`." }, "soft": { "maxItems": 19, "type": "array", "items": { "type": "string", "enum": [ "freeze_authority", "transfer_hook", "permanent_delegate", "non_transferable", "default_frozen", "transfer_fee", "pausable", "unknown_extension", "not_sellable", "mint_authority", "hook_authority", "low_liquidity", "new_token", "top_holders", "unverified", "low_organic", "suspicious", "promoted", "unpriced" ] }, "description": "Warnings to show beside the token, such as `mint_authority` (more can be created) and `hook_authority` (the issuer can add a transfer rule later). `new_token` warns that the mint or its first trading pool is less than a day old; their timestamps remain distinct. Only `unpriced` stops a buy, because a buy's loss cannot be bounded without a price." } }, "required": [ "level", "hard", "soft" ], "description": "Fin's risk verdict on a Solana token, from its mint facts and the venue's data." }, "SolanaTokenLinks": { "type": "object", "properties": { "website": { "description": "Its own site: https, never an X, Telegram or link-shortener address.", "type": "string", "maxLength": 200, "pattern": "^https:\\/\\/[^\\s/?#@:]+(\\/[^\\s?#]*)?$" }, "x": { "description": "Its X profile: `https://x.com/`.", "type": "string", "maxLength": 200, "pattern": "^https:\\/\\/[^\\s/?#@:]+(\\/[^\\s?#]*)?$" }, "telegram": { "description": "Its Telegram: `https://t.me/`.", "type": "string", "maxLength": 200, "pattern": "^https:\\/\\/[^\\s/?#@:]+(\\/[^\\s?#]*)?$" } }, "description": "The token's own links as its listing names them, kept only where they read as a site, an X profile or a Telegram channel. They are its creator's claims, not Fin's; absent when none reads cleanly." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a token chart 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 /v1/solana/tokens/{mint}/chart` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "in": "path", "name": "mint", "required": true, "description": "The token's mint address. Symbols are not unique, so find the mint with Search Solana tokens." } ] ``` ## Query parameters ```json [ { "schema": { "default": "1h", "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "1d" ] }, "in": "query", "name": "interval", "required": false, "description": "How wide each point is: 1m, 5m, 15m, 1h, 4h or 1d. The chart shows the latest 200 points. Defaults to 1h." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/solana/tokens/YOUR_MINT/chart' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The token's closing prices, or why there are none. ```json { "description": "The token's closing prices, or why there are none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenChart" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.getTokenChart", "summary": "Get a token chart", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "default": "1h", "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "1d" ] }, "in": "query", "name": "interval", "required": false, "description": "How wide each point is: 1m, 5m, 15m, 1h, 4h or 1d. The chart shows the latest 200 points. Defaults to 1h." }, { "schema": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "in": "path", "name": "mint", "required": true, "description": "The token's mint address. Symbols are not unique, so find the mint with Search Solana tokens." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The token's closing prices, or why there are none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenChart" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "SolanaTokenChart": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "A pool priced the token." }, "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "interval": { "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "1d" ], "description": "How wide each point is: one, five or fifteen minutes, one or four hours, or one day." }, "pool": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The pool the prices come from: the token's deepest, by the liquidity in it." }, "source": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "CoinGecko", "GeckoTerminal" ], "description": "Who the prices come from." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When they were read." } }, "required": [ "name", "observedAt" ], "description": "Where the prices come from and when they were read." }, "coverage": { "description": "Actual history coverage and freshness; short or gapped history does not support a longer trend claim.", "type": "object", "properties": { "firstAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "lastAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "sampleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "coveredSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expectedIntervalSeconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "completedThrough": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "gaps": { "type": "string", "enum": [ "none", "detected", "unknown" ] }, "status": { "type": "string", "enum": [ "ready", "limited", "stale" ] } }, "required": [ "firstAt", "lastAt", "sampleCount", "coveredSeconds", "expectedIntervalSeconds", "gaps", "status" ] }, "points": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this point's period began." }, "closeUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The price at the close of the period, in US dollars per whole token." }, "ohlcv": { "description": "Exact USD open/high/low and traded volume for this pool's candle, when all are valid and coherent with its close. Not token-wide volume or an execution quote. The latest candle may still be forming; use coverage.completedThrough for closed-period analysis.", "type": "object", "properties": { "openUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "highUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "lowUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "volumeUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" } }, "required": [ "openUsd", "highUsd", "lowUsd", "volumeUsd" ] } }, "required": [ "time", "closeUsd" ] }, "description": "Closing prices with available pool OHLCV, oldest first." } }, "required": [ "status", "mint", "interval", "pool", "source", "points" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "No chart could be drawn." }, "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "interval": { "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "1d" ], "description": "How wide each point is: one, five or fifteen minutes, one or four hours, or one day." }, "reason": { "type": "string", "enum": [ "no_pool", "provider_unavailable", "invalid_response" ], "description": "`no_pool` when no pool prices the token; the others when the price provider could not be read." } }, "required": [ "status", "mint", "interval", "reason" ] } ], "description": "A token's recent closing prices from its deepest pool, or why there are none." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a token's holders 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 /v1/solana/tokens/{mint}/holders` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "in": "path", "name": "mint", "required": true, "description": "The token's mint address. Symbols are not unique, so find the mint with Search Solana tokens." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/solana/tokens/YOUR_MINT/holders' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The token's largest holders, or why there are none. ```json { "description": "The token's largest holders, or why there are none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenHolders" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.getTokenHolders", "summary": "Get a token's holders", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "in": "path", "name": "mint", "required": true, "description": "The token's mint address. Symbols are not unique, so find the mint with Search Solana tokens." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The token's largest holders, or why there are none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaTokenHolders" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "SolanaTokenHolders": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "observed", "description": "The chain answered." }, "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "The mint's decimals." }, "supplyRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The supply the shares are of, in the token's smallest unit." }, "holders": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/SolanaTokenHolder" }, "description": "The largest holders, largest first, each owner once with all its accounts added up." }, "holderChange": { "anyOf": [ { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "1h", "6h", "24h" ], "description": "The trailing window the change is over." }, "pct": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "How much the number of wallets holding it changed over the window, in percent: `-1.5` is down 1.5%." } }, "required": [ "window", "pct" ] } }, { "type": "null" } ], "description": "The change in how many wallets hold it, per window, as a percent the data source states; never a count of wallets. Null when it states none." }, "source": { "type": "object", "properties": { "name": { "type": "string", "const": "Solana", "description": "Read from the chain itself." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was read." } }, "required": [ "name", "observedAt" ], "description": "Where the holders come from and when they were read." } }, "required": [ "status", "mint", "decimals", "supplyRaw", "holders", "holderChange", "source" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable", "description": "No holders could be read." }, "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address." }, "reason": { "type": "string", "enum": [ "rpc_unavailable", "unreadable_mint" ], "description": "`rpc_unavailable` when the chain could not be read just now; `unreadable_mint` when the mint's account is not one Fin can read a supply from." } }, "required": [ "status", "mint", "reason" ] } ], "description": "A token's largest holders, read from the chain, or why there are none." }, "SolanaTokenHolder": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Its place by balance, from 1." }, "owner": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The address that owns the balance." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What it holds, in the token's smallest unit." }, "sharePct": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "Its share of the supply in percent, cut to two decimals: `6.12`, or `0.00` below a hundredth of a percent." }, "kind": { "type": "string", "enum": [ "wallet", "program" ], "description": "`wallet` for an ordinary account; `program` for one a program controls, such as a pool, a vault or a launchpad's bonding curve, so its balance is not one person's." }, "venue": { "description": "Whose pool or bonding curve holds the balance, for a `program` holder Fin recognizes; absent for any other, which is still a pool or a vault if its `kind` is `program`.", "type": "string", "enum": [ "pump_fun", "pumpswap", "meteora", "raydium", "orca", "launchlab" ] }, "creator": { "type": "boolean", "description": "True when the owner is the wallet that created the token, as Jupiter names it." } }, "required": [ "rank", "owner", "amountRaw", "sharePct", "kind", "creator" ], "description": "One of a token's largest holders." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a token icon 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. `GET /v1/solana/tokens/{mint}/icon` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "in": "path", "name": "mint", "required": true, "description": "The token's mint address. Symbols are not unique, so find the mint with Search Solana tokens." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/solana/tokens/YOUR_MINT/icon' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The icon's bytes, as `Content-Type` names them. ```json { "description": "The icon's bytes, as `Content-Type` names them.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "solana.getTokenIcon", "summary": "Get a token icon", "tags": [ "solana" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$" }, "in": "path", "name": "mint", "required": true, "description": "The token's mint address. Symbols are not unique, so find the mint with Search Solana tokens." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The icon's bytes, as `Content-Type` names them.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List suggestions 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 /v1/users/{userId}/suggestions` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "default": "home", "type": "string", "pattern": "^(home|orders|automations|swap|earn|asset:asset_[a-f0-9]{64})$" }, "in": "query", "name": "surface", "required": false, "description": "The page asking; `home` by default." }, { "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z][\\w+-]*(?:\\/[\\w+-]+)*$" }, "in": "query", "name": "timeZone", "required": false, "description": "The user's time zone as an IANA name, such as `America/New_York`: dates in titles, reasons and new schedules read in it. Without it they read in UTC, and Fin suggests no new schedule." }, { "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "The country the user is reading from, as an uppercase ISO 3166-1 alpha-2 code your server resolved, never the browser's word. A move on a tokenized stock shows only where stocks are available; without it, none shows." }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "perpsAllowed", "required": false, "description": "`true` when your app lets this user fund perpetuals where they are now; without it, no perps move shows." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/suggestions' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 What Fin suggests for this page. ```json { "description": "What Fin suggests for this page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSuggestions" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "suggestions.list", "summary": "List suggestions", "tags": [ "suggestions" ], "description": "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.", "parameters": [ { "schema": { "default": "home", "type": "string", "pattern": "^(home|orders|automations|swap|earn|asset:asset_[a-f0-9]{64})$" }, "in": "query", "name": "surface", "required": false, "description": "The page asking; `home` by default." }, { "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z][\\w+-]*(?:\\/[\\w+-]+)*$" }, "in": "query", "name": "timeZone", "required": false, "description": "The user's time zone as an IANA name, such as `America/New_York`: dates in titles, reasons and new schedules read in it. Without it they read in UTC, and Fin suggests no new schedule." }, { "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "The country the user is reading from, as an uppercase ISO 3166-1 alpha-2 code your server resolved, never the browser's word. A move on a tokenized stock shows only where stocks are available; without it, none shows." }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "perpsAllowed", "required": false, "description": "`true` when your app lets this user fund perpetuals where they are now; without it, no perps move shows." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "What Fin suggests for this page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSuggestions" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "PageSuggestions": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "thinking", "failed" ], "description": "`ready` with what Fin suggests here, `thinking` while Fin reads an account it has nothing saved for yet, or `failed` when it could not look." }, "updating": { "type": "boolean", "description": "Fin is reading the account again in the background; the suggestions here hold meanwhile." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "budget_exhausted", "rate_limited", "model_unavailable", "model_timeout", "invalid_output" ] }, { "type": "null" } ], "description": "Why Fin could not look, when `status` is `failed`; null otherwise." }, "retryable": { "type": "boolean", "description": "Whether reading again can help. False when the user's AI spending limit or the hourly limit refused: only time resets those, so offer no Try again." }, "suggestions": { "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/SuggestedMove" }, "description": "What Fin suggests for this page, best first; empty when nothing needs the user." }, "calm": { "anyOf": [ { "type": "object", "properties": { "watching": { "type": "object", "properties": { "orders": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Resting orders." }, "automations": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Automations that are on." } }, "required": [ "orders", "automations" ], "description": "What Fin keeps an eye on." } }, "required": [ "watching" ] }, { "type": "null" } ], "description": "When `status` is `ready` and nothing needs the user; null otherwise." } }, "required": [ "status", "updating", "failureReason", "retryable", "suggestions", "calm" ], "description": "What Fin suggests for one page of your app, from its latest read of the whole account." }, "SuggestedMove": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The suggestion's id. The same move in a later read keeps it." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The move, verb first, with its exact terms: `Move your NEAR buy to $4.80`." }, "reason": { "type": "string", "minLength": 1, "maxLength": 280, "description": "Why, in one sentence; Fin filled in every figure from the account." }, "review": { "$ref": "#/components/schemas/ReviewTerms" }, "surfaces": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^(home|orders|automations|swap|earn|asset:asset_[a-f0-9]{64})$", "description": "A page of your app: `home`, `orders`, `automations`, `swap`, `earn`, or one asset's page as `asset:` and its `assetId` from Get balances." }, "description": "The pages it belongs on; `home` is always one." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it stops showing, unless the account or the market moves it on sooner." } }, "required": [ "id", "title", "reason", "review", "surfaces", "expiresAt" ], "description": "One move Fin suggests on the user's own money, and the exact terms its review draws. Nothing moves until the user reviews and confirms it." }, "ReviewTerms": { "oneOf": [ { "$ref": "#/components/schemas/SwapReview" }, { "$ref": "#/components/schemas/LimitOrderReview" }, { "$ref": "#/components/schemas/OrderMoveReview" }, { "$ref": "#/components/schemas/OrderCancelReview" }, { "$ref": "#/components/schemas/RecurringBuyReview" }, { "$ref": "#/components/schemas/PriceRuleReview" }, { "$ref": "#/components/schemas/SummaryReview" }, { "$ref": "#/components/schemas/DepositReview" }, { "$ref": "#/components/schemas/WithdrawReview" }, { "$ref": "#/components/schemas/SendReview" }, { "$ref": "#/components/schemas/PerpsFundReview" }, { "$ref": "#/components/schemas/AutomationPauseReview" }, { "$ref": "#/components/schemas/AutomationResumeReview" }, { "$ref": "#/components/schemas/AutomationEndReview" }, { "$ref": "#/components/schemas/AutomationChangeReview" }, { "$ref": "#/components/schemas/AskReview" }, { "$ref": "#/components/schemas/OpenReview" } ], "description": "The exact terms a suggestion's review draws, keyed by `kind`: every id and asset the move needs, and the one figure − and + adjust." }, "SwapReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Which review this is." }, "balance": { "description": "What you hold of the asset you pay with.", "$ref": "#/components/schemas/AssetAmount" }, "buy": { "$ref": "#/components/schemas/ReviewAsset" }, "buyPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "One unit of the bought asset now." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "The most the swap may lose, fees and price included." }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "pay": { "description": "What Get a swap quote sells, exactly.", "$ref": "#/components/schemas/AssetAmount" }, "receive": { "description": "What it gets at today's price.", "$ref": "#/components/schemas/AssetAmount" }, "receiveAtLeast": { "description": "The least it gets within the loss limit.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "pay", "receive", "receiveAtLeast" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to swap." } }, "required": [ "kind", "balance", "buy", "buyPriceUsd", "maxValueLossBps", "amount" ], "description": "Swap now: what you pay against what you get." }, "AssetAmount": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/ReviewAsset" }, "amountRaw": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "In the asset's smallest unit, as a decimal integer string: `3000000` is 3 USDC." } }, "required": [ "asset", "amountRaw" ], "description": "An exact amount of one asset." }, "ReviewAsset": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset as Get balances and Prepare an order name it." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 32, "description": "The asset's symbol: `NEAR`, `USDC`, `BTC`, `AAPL`." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36, "description": "The asset's own scale: 24 for NEAR, 6 for USDC, 8 for BTC." }, "network": { "description": "The chain it sits on, for its badge: `near`, `base`; omitted for none.", "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" } }, "required": [ "assetId", "symbol", "decimals" ], "description": "An asset a review names, as it draws and prints it." }, "LimitOrderReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "limit_order", "description": "Which review this is." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "asset": { "description": "The asset the order buys or sells.", "$ref": "#/components/schemas/ReviewAsset" }, "marketPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "One unit of the asset now." }, "spend": { "description": "What a buy spends or a sell sells.", "$ref": "#/components/schemas/AssetAmount" }, "holding": { "description": "A sell: what you hold of the asset.", "$ref": "#/components/schemas/AssetAmount" }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order rests." }, "price": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "$ref": "#/components/schemas/OrderPriceOption" }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "Your price." } }, "required": [ "kind", "side", "asset", "marketPriceUsd", "spend", "expiresInHours", "price" ], "description": "A limit buy or sell: your price against the market." }, "OrderPriceOption": { "type": "object", "properties": { "limitPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Your price in dollars per one unit of the asset." }, "toGoBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "How far the market must move to fill, from today; 0 fills at once." }, "receive": { "description": "What the order gets at this price.", "$ref": "#/components/schemas/AssetAmount" }, "order": { "description": "Prepare an order's request for this price, exactly.", "$ref": "#/components/schemas/OrderRequest" } }, "required": [ "limitPriceUsd", "toGoBps", "receive", "order" ], "description": "A limit order's price, with what depends on it." }, "OrderRequest": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit. It leaves the agent wallet when the order is placed." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. What the order buys comes back to the agent wallet." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The least the order sells at, as bought-asset units per ONE sold unit, written as a plain decimal: \"5\" means at least 5 of the bought asset for each one sold. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order rests before it expires, in whole hours from 1 to 720 (30 days)." }, "context": { "type": "object", "properties": { "country": { "description": "The country the user is making this request from, as an uppercase ISO 3166-1 alpha-2 code such as `GB`, resolved by your server from the request (your edge's IP geolocation), never taken from the browser. A tokenized stock is traded only when this reports a country where it is available.", "type": "string", "pattern": "^[A-Z]{2}$" } }, "description": "What your app knows about the user as they make this request. It applies to this request only, so send it with every request that may trade a tokenized stock." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "limitPrice", "expiresInHours" ], "description": "What to sell, how much, what to buy, the least it sells at and how long it rests; preparing fills in the least the whole order receives. An order of a tokenized stock also needs `context.country`." }, "OrderMoveReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "order_move", "description": "Which review this is." }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's `id`, as List orders names it." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "asset": { "$ref": "#/components/schemas/ReviewAsset" }, "marketPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "One unit of the asset now." }, "spend": { "description": "What the order spends or sells; the move keeps it.", "$ref": "#/components/schemas/AssetAmount" }, "current": { "type": "object", "properties": { "limitPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Its price now." }, "receive": { "description": "What it gets at that price.", "$ref": "#/components/schemas/AssetAmount" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it expires as it rests now." } }, "required": [ "limitPriceUsd", "receive", "expiresAt" ], "description": "The order as it rests now." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the new order rests." }, "price": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "$ref": "#/components/schemas/OrderPriceOption" }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "The new price. An option at the current price renews the order as it is." } }, "required": [ "kind", "orderId", "side", "asset", "marketPriceUsd", "spend", "current", "expiresInHours", "price" ], "description": "Move an order: cancel it and place the same order at a new price, or at its own price to renew it." }, "OrderCancelReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "order_cancel", "description": "Which review this is." }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's `id`, as List orders names it." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "asset": { "$ref": "#/components/schemas/ReviewAsset" }, "spend": { "description": "What the order spends or sells.", "$ref": "#/components/schemas/AssetAmount" }, "limitPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Its price." }, "placedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was placed." }, "filledBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "How much has filled: 0 is nothing." }, "returns": { "description": "What comes back to the account.", "$ref": "#/components/schemas/AssetAmount" }, "filled": { "description": "What has filled and stays; omitted for none.", "$ref": "#/components/schemas/AssetAmount" }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "kind", "orderId", "side", "asset", "spend", "limitPriceUsd", "placedAt", "filledBps", "returns" ], "description": "Cancel an order: what it was, and what comes back." }, "RecurringBuyReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "recurring_buy", "description": "Which review this is." }, "asset": { "description": "What each run buys.", "$ref": "#/components/schemas/ReviewAsset" }, "balance": { "description": "What each run spends from, and what you hold of it.", "$ref": "#/components/schemas/AssetAmount" }, "schedule": { "$ref": "#/components/schemas/ReviewSchedule" }, "upcoming": { "maxItems": 8, "type": "array", "items": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "description": "The next runs, first first." }, "maxRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many buys it makes at most." }, "endsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it ends." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "The most one buy may lose." }, "askEachTime": { "type": "boolean", "description": "Fin's pick for asking before each buy." }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "perRun": { "$ref": "#/components/schemas/RunSpend" }, "receiveEach": { "description": "What each buy gets at today's price.", "$ref": "#/components/schemas/AssetAmount" }, "runsCovered": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many of `upcoming` your balance pays for." } }, "required": [ "perRun", "receiveEach", "runsCovered" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "What each run spends." } }, "required": [ "kind", "asset", "balance", "schedule", "upcoming", "maxRuns", "endsAt", "maxValueLossBps", "askEachTime", "amount" ], "description": "A recurring buy: the runs your money covers." }, "ReviewSchedule": { "type": "object", "properties": { "cadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "How often it runs." }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Local time of day, 24-hour: `09:00`." }, "weekday": { "description": "A weekly schedule's day.", "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "dayOfMonth": { "description": "A monthly schedule's day.", "type": "integer", "minimum": 1, "maximum": 28 }, "timeZone": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z][\\w+-]*(?:\\/[\\w+-]+)*$", "description": "The IANA zone it keeps: `Europe/London`." } }, "required": [ "cadence", "time", "timeZone" ], "description": "When a schedule runs, in the zone it keeps." }, "RunSpend": { "anyOf": [ { "$ref": "#/components/schemas/AssetAmount" }, { "$ref": "#/components/schemas/DollarAmount" } ], "description": "What one run of an automation spends: an exact amount of an asset (`1 USDC`), or dollars of what it buys (`$1 of NEAR`). Fin works out every figure that follows from it either way." }, "DollarAmount": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Dollars of what it buys: `1` reads `$1 of NEAR`." } }, "required": [ "usd" ], "description": "A dollar figure an automation spends." }, "PriceRuleReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "price_rule", "description": "Which review this is." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "direction": { "type": "string", "enum": [ "below", "above" ], "description": "Whether it runs once the price drops below its line or rises above it." }, "asset": { "description": "The asset it watches and trades.", "$ref": "#/components/schemas/ReviewAsset" }, "marketPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "One unit of the asset now." }, "spend": { "description": "What a buy spends or a sell sells.", "$ref": "#/components/schemas/AssetAmount" }, "holding": { "description": "A sell: what you hold of the asset.", "$ref": "#/components/schemas/AssetAmount" }, "history": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "closesUsd": { "maxItems": 400, "type": "array", "items": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "US dollars as exact decimal text, such as `4.80` or `82732`; never a float." }, "description": "Daily closes, oldest first." } }, "required": [ "from", "to", "closesUsd" ], "description": "The chart's line." }, "maxRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many times it runs: 1 runs once." }, "checkEveryMinutes": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "How often it checks the price." }, "endsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it ends." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "The most it may lose when it runs." }, "threshold": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "thresholdUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "The price that starts it." }, "distanceBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "How far that is from today's price." }, "receive": { "description": "A sell: the least it receives there; a buy: what it buys there.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "thresholdUsd", "distanceBps", "receive" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "The price line." } }, "required": [ "kind", "side", "direction", "asset", "marketPriceUsd", "spend", "history", "maxRuns", "checkEveryMinutes", "endsAt", "maxValueLossBps", "threshold" ], "description": "Buy or sell once a price crosses a line." }, "SummaryReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "summary", "description": "Which review this is." }, "schedule": { "$ref": "#/components/schemas/ReviewSchedule" }, "preview": { "type": "string", "minLength": 1, "maxLength": 600, "description": "A sample of the first summary, written by Fin from the account: plain text." }, "thread": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The page whose thread it writes in: `home`." }, "time": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Local time of day, 24-hour." }, "firstAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the first one comes." } }, "required": [ "time", "firstAt" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "The time of day it comes." } }, "required": [ "kind", "schedule", "preview", "thread", "time" ], "description": "A summary Fin writes on a schedule; no money moves." }, "DepositReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "deposit", "description": "Which review this is." }, "asset": { "description": "What is sent and on which chain.", "$ref": "#/components/schemas/ReviewAsset" }, "room": { "description": "The deposit limit, what the account holds against it, and what is left; omitted when no limit applies.", "type": "object", "properties": { "limitUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "US dollars as exact decimal text, such as `4.80` or `82732`; never a float." }, "usedUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "US dollars as exact decimal text, such as `4.80` or `82732`; never a float." }, "leftUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "US dollars as exact decimal text, such as `4.80` or `82732`; never a float." } }, "required": [ "limitUsd", "usedUsd", "leftUsd" ] }, "networkFeeUsd": { "description": "Fin's estimate of the sending chain's fee; omitted without one.", "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$" }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "deposit": { "$ref": "#/components/schemas/AssetAmount" }, "usd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Its worth now." }, "leftAfterUsd": { "description": "What is left of the room after it; omitted when no limit applies.", "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$" } }, "required": [ "deposit", "usd" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to deposit." } }, "required": [ "kind", "asset", "amount" ], "description": "Add money from the connected wallet." }, "WithdrawReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw", "description": "Which review this is." }, "balance": { "description": "What you hold of the asset.", "$ref": "#/components/schemas/AssetAmount" }, "destination": { "description": "Your own wallet, the only place a withdrawal goes, when Fin knows its address; otherwise your app's own connected wallet.", "type": "object", "properties": { "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "The wallet's address on its network." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The network, as List supported assets names it." } }, "required": [ "address", "network" ] }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "withdraw": { "$ref": "#/components/schemas/AssetAmount" }, "fee": { "description": "The fee, from a real quote; omitted without one.", "$ref": "#/components/schemas/AssetAmount" }, "arrivesAtLeast": { "description": "The least that arrives, from a real quote; omitted without one.", "$ref": "#/components/schemas/AssetAmount" }, "stays": { "description": "What stays in the account.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "withdraw", "stays" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to withdraw." } }, "required": [ "kind", "balance", "amount" ], "description": "Move money back to your own wallet." }, "SendReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Which review this is." }, "contactId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your app's contact." }, "purpose": { "description": "What it is for, in Fin's words.", "type": "string", "maxLength": 80 }, "balance": { "$ref": "#/components/schemas/AssetAmount" }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "send": { "$ref": "#/components/schemas/AssetAmount" }, "fee": { "$ref": "#/components/schemas/AssetAmount" }, "arrivesAtLeast": { "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "send" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to send." } }, "required": [ "kind", "contactId", "balance", "amount" ], "description": "Send to a saved contact. Fin does not suggest it yet." }, "PerpsFundReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "perps_fund", "description": "Which review this is." }, "balance": { "$ref": "#/components/schemas/AssetAmount" }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "move": { "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "move" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to move." } }, "required": [ "kind", "balance", "amount" ], "description": "Move margin to the perps account." }, "AutomationPauseReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "automation_pause", "description": "Which review this is." }, "automation": { "$ref": "#/components/schemas/ReviewAutomation" }, "upcoming": { "maxItems": 8, "type": "array", "items": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "description": "The next runs it would make, all skipped while paused." }, "coverage": { "$ref": "#/components/schemas/ReviewCoverage" } }, "required": [ "kind", "automation", "upcoming", "coverage" ], "description": "Pause an automation." }, "ReviewAutomation": { "type": "object", "properties": { "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's own name, as its owner wrote it." }, "trigger": { "type": "string", "enum": [ "schedule", "price-drop", "price-rise", "event" ], "description": "What starts its runs. An `event` one runs when something happens and has no price or time to draw." }, "asset": { "description": "The asset it buys or sells.", "$ref": "#/components/schemas/ReviewAsset" }, "schedule": { "description": "A scheduled one's schedule.", "$ref": "#/components/schemas/ReviewSchedule" }, "nextRunAt": { "description": "When it runs next, while it is on.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "pausedAt": { "description": "When it was paused, when Fin can tell.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "automationId", "name", "trigger" ], "description": "An automation a review changes." }, "ReviewCoverage": { "type": "object", "properties": { "by": { "description": "The money that pays: the spendable balance.", "$ref": "#/components/schemas/AssetAmount" }, "byDeposit": { "type": "boolean", "description": "True when that balance is there because a deposit landed since the last run." }, "runsCovered": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many of the coming runs it pays for; 0 pays for none." }, "runsLeft": { "description": "Runs left before the automation ends.", "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "by", "byDeposit", "runsCovered" ], "description": "What pays for a schedule's coming runs." }, "AutomationResumeReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "automation_resume", "description": "Which review this is." }, "automation": { "$ref": "#/components/schemas/ReviewAutomation" }, "upcoming": { "maxItems": 8, "type": "array", "items": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "description": "The next runs, first first." }, "coverage": { "$ref": "#/components/schemas/ReviewCoverage" }, "endsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When its approval ends." }, "runsUsed": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Runs it has made." }, "maxRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Runs its approval allows in all." } }, "required": [ "kind", "automation", "upcoming", "coverage", "endsAt", "runsUsed", "maxRuns" ], "description": "Resume a paused automation under the approval it already has." }, "AutomationEndReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "automation_end", "description": "Which review this is." }, "automation": { "$ref": "#/components/schemas/ReviewAutomation" }, "runs": { "type": "object", "properties": { "done": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Runs it made." }, "total": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Runs its approval allowed." } }, "required": [ "done", "total" ], "description": "Runs made of the runs approved." }, "stillCovered": { "description": "Another automation of yours still watching the asset.", "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "direction": { "type": "string", "enum": [ "below", "above" ], "description": "Whether it runs below its line or above it." }, "thresholdUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Its line." } }, "required": [ "side", "direction", "thresholdUsd" ] } }, "required": [ "kind", "automation", "runs" ], "description": "End an automation: its history stays, its runs stop." }, "AutomationChangeReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "automation_change", "description": "Which review this is." }, "automation": { "$ref": "#/components/schemas/ReviewAutomation" }, "balance": { "description": "What each run spends from.", "$ref": "#/components/schemas/AssetAmount" }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "The most one run may lose." }, "current": { "type": "object", "properties": { "perRun": { "$ref": "#/components/schemas/RunSpend" }, "lastsRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many runs the balance pays for as it is." } }, "required": [ "perRun", "lastsRuns" ], "description": "As it runs today." }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "perRun": { "$ref": "#/components/schemas/RunSpend" }, "receiveEach": { "description": "What each run gets at today's price.", "$ref": "#/components/schemas/AssetAmount" }, "lastsRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many runs the balance pays for at this amount." }, "lastsUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the balance runs out at this amount." } }, "required": [ "perRun", "receiveEach", "lastsRuns", "lastsUntil" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "What each run spends." } }, "required": [ "kind", "automation", "balance", "maxValueLossBps", "current", "amount" ], "description": "Change what each run of an automation spends." }, "AskReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "ask", "description": "Which review this is." }, "question": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The question the chat opens with." } }, "required": [ "kind", "question" ], "description": "Ask Fin: opens the page's chat with the question." }, "OpenReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Which review this is." }, "targetId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Your app's id for the form." }, "amount": { "description": "What Fin fills in.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "kind", "targetId" ], "description": "A product Fin cannot run for you: its own form, filled in. Fin does not suggest it yet." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a suggestion's review 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. `GET /v1/users/{userId}/suggestions/{suggestionId}/review` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "suggestionId", "required": true, "description": "The suggestion's `id`, from List suggestions." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z][\\w+-]*(?:\\/[\\w+-]+)*$" }, "in": "query", "name": "timeZone", "required": false, "description": "The user's time zone as an IANA name, such as `America/New_York`: dates in titles, reasons and new schedules read in it. Without it they read in UTC, and Fin suggests no new schedule." }, { "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "The country the user is reading from, as an uppercase ISO 3166-1 alpha-2 code your server resolved, never the browser's word. A move on a tokenized stock shows only where stocks are available; without it, none shows." }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "perpsAllowed", "required": false, "description": "`true` when your app lets this user fund perpetuals where they are now; without it, no perps move shows." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/suggestions/YOUR_SUGGESTION_ID/review' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The suggestion, checked again, with fresh terms. ```json { "description": "The suggestion, checked again, with fresh terms.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestedMove" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `suggestion_changed` — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again ```json { "description": "The operation lost to the current state.\n\n- `suggestion_changed` — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "suggestions.review", "summary": "Get a suggestion's review", "tags": [ "suggestions" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z][\\w+-]*(?:\\/[\\w+-]+)*$" }, "in": "query", "name": "timeZone", "required": false, "description": "The user's time zone as an IANA name, such as `America/New_York`: dates in titles, reasons and new schedules read in it. Without it they read in UTC, and Fin suggests no new schedule." }, { "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "in": "query", "name": "country", "required": false, "description": "The country the user is reading from, as an uppercase ISO 3166-1 alpha-2 code your server resolved, never the browser's word. A move on a tokenized stock shows only where stocks are available; without it, none shows." }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "perpsAllowed", "required": false, "description": "`true` when your app lets this user fund perpetuals where they are now; without it, no perps move shows." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "suggestionId", "required": true, "description": "The suggestion's `id`, from List suggestions." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The suggestion, checked again, with fresh terms.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestedMove" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `suggestion_changed` — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "SuggestedMove": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The suggestion's id. The same move in a later read keeps it." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The move, verb first, with its exact terms: `Move your NEAR buy to $4.80`." }, "reason": { "type": "string", "minLength": 1, "maxLength": 280, "description": "Why, in one sentence; Fin filled in every figure from the account." }, "review": { "$ref": "#/components/schemas/ReviewTerms" }, "surfaces": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^(home|orders|automations|swap|earn|asset:asset_[a-f0-9]{64})$", "description": "A page of your app: `home`, `orders`, `automations`, `swap`, `earn`, or one asset's page as `asset:` and its `assetId` from Get balances." }, "description": "The pages it belongs on; `home` is always one." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it stops showing, unless the account or the market moves it on sooner." } }, "required": [ "id", "title", "reason", "review", "surfaces", "expiresAt" ], "description": "One move Fin suggests on the user's own money, and the exact terms its review draws. Nothing moves until the user reviews and confirms it." }, "ReviewTerms": { "oneOf": [ { "$ref": "#/components/schemas/SwapReview" }, { "$ref": "#/components/schemas/LimitOrderReview" }, { "$ref": "#/components/schemas/OrderMoveReview" }, { "$ref": "#/components/schemas/OrderCancelReview" }, { "$ref": "#/components/schemas/RecurringBuyReview" }, { "$ref": "#/components/schemas/PriceRuleReview" }, { "$ref": "#/components/schemas/SummaryReview" }, { "$ref": "#/components/schemas/DepositReview" }, { "$ref": "#/components/schemas/WithdrawReview" }, { "$ref": "#/components/schemas/SendReview" }, { "$ref": "#/components/schemas/PerpsFundReview" }, { "$ref": "#/components/schemas/AutomationPauseReview" }, { "$ref": "#/components/schemas/AutomationResumeReview" }, { "$ref": "#/components/schemas/AutomationEndReview" }, { "$ref": "#/components/schemas/AutomationChangeReview" }, { "$ref": "#/components/schemas/AskReview" }, { "$ref": "#/components/schemas/OpenReview" } ], "description": "The exact terms a suggestion's review draws, keyed by `kind`: every id and asset the move needs, and the one figure − and + adjust." }, "SwapReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Which review this is." }, "balance": { "description": "What you hold of the asset you pay with.", "$ref": "#/components/schemas/AssetAmount" }, "buy": { "$ref": "#/components/schemas/ReviewAsset" }, "buyPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "One unit of the bought asset now." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "The most the swap may lose, fees and price included." }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "pay": { "description": "What Get a swap quote sells, exactly.", "$ref": "#/components/schemas/AssetAmount" }, "receive": { "description": "What it gets at today's price.", "$ref": "#/components/schemas/AssetAmount" }, "receiveAtLeast": { "description": "The least it gets within the loss limit.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "pay", "receive", "receiveAtLeast" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to swap." } }, "required": [ "kind", "balance", "buy", "buyPriceUsd", "maxValueLossBps", "amount" ], "description": "Swap now: what you pay against what you get." }, "AssetAmount": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/ReviewAsset" }, "amountRaw": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "In the asset's smallest unit, as a decimal integer string: `3000000` is 3 USDC." } }, "required": [ "asset", "amountRaw" ], "description": "An exact amount of one asset." }, "ReviewAsset": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset as Get balances and Prepare an order name it." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 32, "description": "The asset's symbol: `NEAR`, `USDC`, `BTC`, `AAPL`." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36, "description": "The asset's own scale: 24 for NEAR, 6 for USDC, 8 for BTC." }, "network": { "description": "The chain it sits on, for its badge: `near`, `base`; omitted for none.", "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" } }, "required": [ "assetId", "symbol", "decimals" ], "description": "An asset a review names, as it draws and prints it." }, "LimitOrderReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "limit_order", "description": "Which review this is." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "asset": { "description": "The asset the order buys or sells.", "$ref": "#/components/schemas/ReviewAsset" }, "marketPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "One unit of the asset now." }, "spend": { "description": "What a buy spends or a sell sells.", "$ref": "#/components/schemas/AssetAmount" }, "holding": { "description": "A sell: what you hold of the asset.", "$ref": "#/components/schemas/AssetAmount" }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order rests." }, "price": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "$ref": "#/components/schemas/OrderPriceOption" }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "Your price." } }, "required": [ "kind", "side", "asset", "marketPriceUsd", "spend", "expiresInHours", "price" ], "description": "A limit buy or sell: your price against the market." }, "OrderPriceOption": { "type": "object", "properties": { "limitPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Your price in dollars per one unit of the asset." }, "toGoBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "How far the market must move to fill, from today; 0 fills at once." }, "receive": { "description": "What the order gets at this price.", "$ref": "#/components/schemas/AssetAmount" }, "order": { "description": "Prepare an order's request for this price, exactly.", "$ref": "#/components/schemas/OrderRequest" } }, "required": [ "limitPriceUsd", "toGoBps", "receive", "order" ], "description": "A limit order's price, with what depends on it." }, "OrderRequest": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit. It leaves the agent wallet when the order is placed." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. What the order buys comes back to the agent wallet." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The least the order sells at, as bought-asset units per ONE sold unit, written as a plain decimal: \"5\" means at least 5 of the bought asset for each one sold. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order rests before it expires, in whole hours from 1 to 720 (30 days)." }, "context": { "type": "object", "properties": { "country": { "description": "The country the user is making this request from, as an uppercase ISO 3166-1 alpha-2 code such as `GB`, resolved by your server from the request (your edge's IP geolocation), never taken from the browser. A tokenized stock is traded only when this reports a country where it is available.", "type": "string", "pattern": "^[A-Z]{2}$" } }, "description": "What your app knows about the user as they make this request. It applies to this request only, so send it with every request that may trade a tokenized stock." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "limitPrice", "expiresInHours" ], "description": "What to sell, how much, what to buy, the least it sells at and how long it rests; preparing fills in the least the whole order receives. An order of a tokenized stock also needs `context.country`." }, "OrderMoveReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "order_move", "description": "Which review this is." }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's `id`, as List orders names it." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "asset": { "$ref": "#/components/schemas/ReviewAsset" }, "marketPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "One unit of the asset now." }, "spend": { "description": "What the order spends or sells; the move keeps it.", "$ref": "#/components/schemas/AssetAmount" }, "current": { "type": "object", "properties": { "limitPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Its price now." }, "receive": { "description": "What it gets at that price.", "$ref": "#/components/schemas/AssetAmount" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it expires as it rests now." } }, "required": [ "limitPriceUsd", "receive", "expiresAt" ], "description": "The order as it rests now." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the new order rests." }, "price": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "$ref": "#/components/schemas/OrderPriceOption" }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "The new price. An option at the current price renews the order as it is." } }, "required": [ "kind", "orderId", "side", "asset", "marketPriceUsd", "spend", "current", "expiresInHours", "price" ], "description": "Move an order: cancel it and place the same order at a new price, or at its own price to renew it." }, "OrderCancelReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "order_cancel", "description": "Which review this is." }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's `id`, as List orders names it." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "asset": { "$ref": "#/components/schemas/ReviewAsset" }, "spend": { "description": "What the order spends or sells.", "$ref": "#/components/schemas/AssetAmount" }, "limitPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Its price." }, "placedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was placed." }, "filledBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "How much has filled: 0 is nothing." }, "returns": { "description": "What comes back to the account.", "$ref": "#/components/schemas/AssetAmount" }, "filled": { "description": "What has filled and stays; omitted for none.", "$ref": "#/components/schemas/AssetAmount" }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "kind", "orderId", "side", "asset", "spend", "limitPriceUsd", "placedAt", "filledBps", "returns" ], "description": "Cancel an order: what it was, and what comes back." }, "RecurringBuyReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "recurring_buy", "description": "Which review this is." }, "asset": { "description": "What each run buys.", "$ref": "#/components/schemas/ReviewAsset" }, "balance": { "description": "What each run spends from, and what you hold of it.", "$ref": "#/components/schemas/AssetAmount" }, "schedule": { "$ref": "#/components/schemas/ReviewSchedule" }, "upcoming": { "maxItems": 8, "type": "array", "items": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "description": "The next runs, first first." }, "maxRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many buys it makes at most." }, "endsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it ends." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "The most one buy may lose." }, "askEachTime": { "type": "boolean", "description": "Fin's pick for asking before each buy." }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "perRun": { "$ref": "#/components/schemas/RunSpend" }, "receiveEach": { "description": "What each buy gets at today's price.", "$ref": "#/components/schemas/AssetAmount" }, "runsCovered": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many of `upcoming` your balance pays for." } }, "required": [ "perRun", "receiveEach", "runsCovered" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "What each run spends." } }, "required": [ "kind", "asset", "balance", "schedule", "upcoming", "maxRuns", "endsAt", "maxValueLossBps", "askEachTime", "amount" ], "description": "A recurring buy: the runs your money covers." }, "ReviewSchedule": { "type": "object", "properties": { "cadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "How often it runs." }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Local time of day, 24-hour: `09:00`." }, "weekday": { "description": "A weekly schedule's day.", "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "dayOfMonth": { "description": "A monthly schedule's day.", "type": "integer", "minimum": 1, "maximum": 28 }, "timeZone": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z][\\w+-]*(?:\\/[\\w+-]+)*$", "description": "The IANA zone it keeps: `Europe/London`." } }, "required": [ "cadence", "time", "timeZone" ], "description": "When a schedule runs, in the zone it keeps." }, "RunSpend": { "anyOf": [ { "$ref": "#/components/schemas/AssetAmount" }, { "$ref": "#/components/schemas/DollarAmount" } ], "description": "What one run of an automation spends: an exact amount of an asset (`1 USDC`), or dollars of what it buys (`$1 of NEAR`). Fin works out every figure that follows from it either way." }, "DollarAmount": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Dollars of what it buys: `1` reads `$1 of NEAR`." } }, "required": [ "usd" ], "description": "A dollar figure an automation spends." }, "PriceRuleReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "price_rule", "description": "Which review this is." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "direction": { "type": "string", "enum": [ "below", "above" ], "description": "Whether it runs once the price drops below its line or rises above it." }, "asset": { "description": "The asset it watches and trades.", "$ref": "#/components/schemas/ReviewAsset" }, "marketPriceUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "One unit of the asset now." }, "spend": { "description": "What a buy spends or a sell sells.", "$ref": "#/components/schemas/AssetAmount" }, "holding": { "description": "A sell: what you hold of the asset.", "$ref": "#/components/schemas/AssetAmount" }, "history": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "closesUsd": { "maxItems": 400, "type": "array", "items": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "US dollars as exact decimal text, such as `4.80` or `82732`; never a float." }, "description": "Daily closes, oldest first." } }, "required": [ "from", "to", "closesUsd" ], "description": "The chart's line." }, "maxRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many times it runs: 1 runs once." }, "checkEveryMinutes": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "How often it checks the price." }, "endsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it ends." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "The most it may lose when it runs." }, "threshold": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "thresholdUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "The price that starts it." }, "distanceBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "How far that is from today's price." }, "receive": { "description": "A sell: the least it receives there; a buy: what it buys there.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "thresholdUsd", "distanceBps", "receive" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "The price line." } }, "required": [ "kind", "side", "direction", "asset", "marketPriceUsd", "spend", "history", "maxRuns", "checkEveryMinutes", "endsAt", "maxValueLossBps", "threshold" ], "description": "Buy or sell once a price crosses a line." }, "SummaryReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "summary", "description": "Which review this is." }, "schedule": { "$ref": "#/components/schemas/ReviewSchedule" }, "preview": { "type": "string", "minLength": 1, "maxLength": 600, "description": "A sample of the first summary, written by Fin from the account: plain text." }, "thread": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The page whose thread it writes in: `home`." }, "time": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Local time of day, 24-hour." }, "firstAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the first one comes." } }, "required": [ "time", "firstAt" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "The time of day it comes." } }, "required": [ "kind", "schedule", "preview", "thread", "time" ], "description": "A summary Fin writes on a schedule; no money moves." }, "DepositReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "deposit", "description": "Which review this is." }, "asset": { "description": "What is sent and on which chain.", "$ref": "#/components/schemas/ReviewAsset" }, "room": { "description": "The deposit limit, what the account holds against it, and what is left; omitted when no limit applies.", "type": "object", "properties": { "limitUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "US dollars as exact decimal text, such as `4.80` or `82732`; never a float." }, "usedUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "US dollars as exact decimal text, such as `4.80` or `82732`; never a float." }, "leftUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "US dollars as exact decimal text, such as `4.80` or `82732`; never a float." } }, "required": [ "limitUsd", "usedUsd", "leftUsd" ] }, "networkFeeUsd": { "description": "Fin's estimate of the sending chain's fee; omitted without one.", "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$" }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "deposit": { "$ref": "#/components/schemas/AssetAmount" }, "usd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Its worth now." }, "leftAfterUsd": { "description": "What is left of the room after it; omitted when no limit applies.", "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$" } }, "required": [ "deposit", "usd" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to deposit." } }, "required": [ "kind", "asset", "amount" ], "description": "Add money from the connected wallet." }, "WithdrawReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw", "description": "Which review this is." }, "balance": { "description": "What you hold of the asset.", "$ref": "#/components/schemas/AssetAmount" }, "destination": { "description": "Your own wallet, the only place a withdrawal goes, when Fin knows its address; otherwise your app's own connected wallet.", "type": "object", "properties": { "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "The wallet's address on its network." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The network, as List supported assets names it." } }, "required": [ "address", "network" ] }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "withdraw": { "$ref": "#/components/schemas/AssetAmount" }, "fee": { "description": "The fee, from a real quote; omitted without one.", "$ref": "#/components/schemas/AssetAmount" }, "arrivesAtLeast": { "description": "The least that arrives, from a real quote; omitted without one.", "$ref": "#/components/schemas/AssetAmount" }, "stays": { "description": "What stays in the account.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "withdraw", "stays" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to withdraw." } }, "required": [ "kind", "balance", "amount" ], "description": "Move money back to your own wallet." }, "SendReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Which review this is." }, "contactId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your app's contact." }, "purpose": { "description": "What it is for, in Fin's words.", "type": "string", "maxLength": 80 }, "balance": { "$ref": "#/components/schemas/AssetAmount" }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "send": { "$ref": "#/components/schemas/AssetAmount" }, "fee": { "$ref": "#/components/schemas/AssetAmount" }, "arrivesAtLeast": { "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "send" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to send." } }, "required": [ "kind", "contactId", "balance", "amount" ], "description": "Send to a saved contact. Fin does not suggest it yet." }, "PerpsFundReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "perps_fund", "description": "Which review this is." }, "balance": { "$ref": "#/components/schemas/AssetAmount" }, "etaSeconds": { "description": "Fin's estimate of how long it takes, in seconds, from a real quote; omitted without one, when the review says its usual time.", "type": "integer", "minimum": 1, "maximum": 86400 }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "move": { "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "move" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "How much to move." } }, "required": [ "kind", "balance", "amount" ], "description": "Move margin to the perps account." }, "AutomationPauseReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "automation_pause", "description": "Which review this is." }, "automation": { "$ref": "#/components/schemas/ReviewAutomation" }, "upcoming": { "maxItems": 8, "type": "array", "items": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "description": "The next runs it would make, all skipped while paused." }, "coverage": { "$ref": "#/components/schemas/ReviewCoverage" } }, "required": [ "kind", "automation", "upcoming", "coverage" ], "description": "Pause an automation." }, "ReviewAutomation": { "type": "object", "properties": { "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's own name, as its owner wrote it." }, "trigger": { "type": "string", "enum": [ "schedule", "price-drop", "price-rise", "event" ], "description": "What starts its runs. An `event` one runs when something happens and has no price or time to draw." }, "asset": { "description": "The asset it buys or sells.", "$ref": "#/components/schemas/ReviewAsset" }, "schedule": { "description": "A scheduled one's schedule.", "$ref": "#/components/schemas/ReviewSchedule" }, "nextRunAt": { "description": "When it runs next, while it is on.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "pausedAt": { "description": "When it was paused, when Fin can tell.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "automationId", "name", "trigger" ], "description": "An automation a review changes." }, "ReviewCoverage": { "type": "object", "properties": { "by": { "description": "The money that pays: the spendable balance.", "$ref": "#/components/schemas/AssetAmount" }, "byDeposit": { "type": "boolean", "description": "True when that balance is there because a deposit landed since the last run." }, "runsCovered": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many of the coming runs it pays for; 0 pays for none." }, "runsLeft": { "description": "Runs left before the automation ends.", "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "by", "byDeposit", "runsCovered" ], "description": "What pays for a schedule's coming runs." }, "AutomationResumeReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "automation_resume", "description": "Which review this is." }, "automation": { "$ref": "#/components/schemas/ReviewAutomation" }, "upcoming": { "maxItems": 8, "type": "array", "items": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "An instant in RFC 3339, such as `2026-11-07T09:00:00Z`." }, "description": "The next runs, first first." }, "coverage": { "$ref": "#/components/schemas/ReviewCoverage" }, "endsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When its approval ends." }, "runsUsed": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Runs it has made." }, "maxRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Runs its approval allows in all." } }, "required": [ "kind", "automation", "upcoming", "coverage", "endsAt", "runsUsed", "maxRuns" ], "description": "Resume a paused automation under the approval it already has." }, "AutomationEndReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "automation_end", "description": "Which review this is." }, "automation": { "$ref": "#/components/schemas/ReviewAutomation" }, "runs": { "type": "object", "properties": { "done": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Runs it made." }, "total": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Runs its approval allowed." } }, "required": [ "done", "total" ], "description": "Runs made of the runs approved." }, "stillCovered": { "description": "Another automation of yours still watching the asset.", "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Whether it buys or sells the asset." }, "direction": { "type": "string", "enum": [ "below", "above" ], "description": "Whether it runs below its line or above it." }, "thresholdUsd": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,18})?$", "description": "Its line." } }, "required": [ "side", "direction", "thresholdUsd" ] } }, "required": [ "kind", "automation", "runs" ], "description": "End an automation: its history stays, its runs stop." }, "AutomationChangeReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "automation_change", "description": "Which review this is." }, "automation": { "$ref": "#/components/schemas/ReviewAutomation" }, "balance": { "description": "What each run spends from.", "$ref": "#/components/schemas/AssetAmount" }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "The most one run may lose." }, "current": { "type": "object", "properties": { "perRun": { "$ref": "#/components/schemas/RunSpend" }, "lastsRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many runs the balance pays for as it is." } }, "required": [ "perRun", "lastsRuns" ], "description": "As it runs today." }, "amount": { "type": "object", "properties": { "options": { "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "perRun": { "$ref": "#/components/schemas/RunSpend" }, "receiveEach": { "description": "What each run gets at today's price.", "$ref": "#/components/schemas/AssetAmount" }, "lastsRuns": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "How many runs the balance pays for at this amount." }, "lastsUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the balance runs out at this amount." } }, "required": [ "perRun", "receiveEach", "lastsRuns", "lastsUntil" ] }, "description": "Every value − and + can reach, lowest first, each with what follows from it." }, "suggested": { "type": "integer", "minimum": 0, "maximum": 24, "description": "The option the review opens on: Fin's choice." } }, "required": [ "options", "suggested" ], "description": "What each run spends." } }, "required": [ "kind", "automation", "balance", "maxValueLossBps", "current", "amount" ], "description": "Change what each run of an automation spends." }, "AskReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "ask", "description": "Which review this is." }, "question": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The question the chat opens with." } }, "required": [ "kind", "question" ], "description": "Ask Fin: opens the page's chat with the question." }, "OpenReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Which review this is." }, "targetId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Your app's id for the form." }, "amount": { "description": "What Fin fills in.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "kind", "targetId" ], "description": "A product Fin cannot run for you: its own form, filled in. Fin does not suggest it yet." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Dismiss a suggestion 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. `POST /v1/users/{userId}/suggestions/{suggestionId}/dismiss` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "suggestionId", "required": true, "description": "The suggestion's `id`, from List suggestions." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/suggestions/YOUR_SUGGESTION_ID/dismiss' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 204 The suggestion is set aside. ```json { "description": "The suggestion is set aside." } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "suggestions.dismiss", "summary": "Dismiss a suggestion", "tags": [ "suggestions" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "suggestionId", "required": true, "description": "The suggestion's `id`, from List suggestions." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "204": { "description": "The suggestion is set aside." }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List baskets 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 /v1/users/{userId}/baskets` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/baskets' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The user's baskets and the next page's cursor. ```json { "description": "The user's baskets and the next page's cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasketPage" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `baskets_disabled` — idea baskets are not turned on for this user; hide the Ideas pages and their baskets ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `baskets_disabled` — idea baskets are not turned on for this user; hide the Ideas pages and their baskets", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "baskets.list", "summary": "List baskets", "tags": [ "baskets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's baskets and the next page's cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasketPage" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `baskets_disabled` — idea baskets are not turned on for this user; hide the Ideas pages and their baskets", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "BasketPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BasketSummary" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] }, "BasketSummary": { "type": "object", "properties": { "basketId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "idea": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "type": "string", "enum": [ "draft", "buying", "bought", "partly_bought", "not_bought" ], "description": "`draft`: proposed, not bought. `buying`: approved and its pieces are running. `bought`: every piece done, or every step that did not buy later linked to an order that stands in for it. `partly_bought`: some pieces done, others failed or skipped. `not_bought`: approved but nothing was bought, or the approval was declined or expired." }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The latest revision, or the one bought." }, "budgetUsdc": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, "costUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "The USDC the basket's executed pieces paid; null before anything was bought." }, "valueUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "What the bought positions are worth now, at current prices, plus unused venue money; null when nothing was bought or no price is available." }, "changeUsdc": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$" }, { "type": "null" } ], "description": "Value less cost, in USDC; negative for a loss. Null when either is null." }, "allocation": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "theme": { "type": "string", "minLength": 1, "maxLength": 60 }, "weightBps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "theme", "weightBps" ] }, "description": "The basket's themes and their shares, in basis points." }, "venues": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "intents", "perps", "polymarket" ], "description": "Where a position is bought: `intents` (crypto and tokenized stocks through NEAR Intents), `perps` (a 1x isolated long or short on Hyperliquid) or `polymarket` (an outcome bought on Polymarket)." } }, "unused": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "venue": { "type": "string", "enum": [ "hyperliquid", "polymarket" ] }, "amountUsdc": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, "withdrawTool": { "type": "string", "enum": [ "perps_withdraw", "prediction_withdraw" ] } }, "required": [ "venue", "amountUsdc", "withdrawTool" ] }, "description": "Money a funding step moved to a venue that no order used, capped by what the venue holds now; withdrawing it is a separate approval." }, "unusedUnavailable": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "hyperliquid", "polymarket" ] }, "description": "Venues whose unused money could not be read; unavailable never means zero." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "boughtAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "basketId", "title", "idea", "status", "revision", "budgetUsdc", "costUsdc", "valueUsdc", "changeUsdc", "allocation", "venues", "unused", "unusedUnavailable", "createdAt", "boughtAt" ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a basket 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. `GET /v1/users/{userId}/baskets/{basketId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "basketId", "required": true, "description": "The basket's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/baskets/YOUR_BASKET_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The basket and its estimated position values. ```json { "description": "The basket and its estimated position values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Basket" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `baskets_disabled` — idea baskets are not turned on for this user; hide the Ideas pages and their baskets ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `baskets_disabled` — idea baskets are not turned on for this user; hide the Ideas pages and their baskets", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "baskets.get", "summary": "Get a basket", "tags": [ "baskets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "basketId", "required": true, "description": "The basket's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The basket and its estimated position values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Basket" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `baskets_disabled` — idea baskets are not turned on for this user; hide the Ideas pages and their baskets", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Basket": { "type": "object", "properties": { "basketId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "idea": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "type": "string", "enum": [ "draft", "buying", "bought", "partly_bought", "not_bought" ], "description": "`draft`: proposed, not bought. `buying`: approved and its pieces are running. `bought`: every piece done, or every step that did not buy later linked to an order that stands in for it. `partly_bought`: some pieces done, others failed or skipped. `not_bought`: approved but nothing was bought, or the approval was declined or expired." }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The latest revision, or the one bought." }, "budgetUsdc": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, "costUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "The USDC the basket's executed pieces paid; null before anything was bought." }, "valueUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "What the bought positions are worth now, at current prices, plus unused venue money; null when nothing was bought or no price is available." }, "changeUsdc": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$" }, { "type": "null" } ], "description": "Value less cost, in USDC; negative for a loss. Null when either is null." }, "allocation": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "theme": { "type": "string", "minLength": 1, "maxLength": 60 }, "weightBps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "theme", "weightBps" ] }, "description": "The basket's themes and their shares, in basis points." }, "venues": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "intents", "perps", "polymarket" ], "description": "Where a position is bought: `intents` (crypto and tokenized stocks through NEAR Intents), `perps` (a 1x isolated long or short on Hyperliquid) or `polymarket` (an outcome bought on Polymarket)." } }, "unused": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "venue": { "type": "string", "enum": [ "hyperliquid", "polymarket" ] }, "amountUsdc": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, "withdrawTool": { "type": "string", "enum": [ "perps_withdraw", "prediction_withdraw" ] } }, "required": [ "venue", "amountUsdc", "withdrawTool" ] }, "description": "Money a funding step moved to a venue that no order used, capped by what the venue holds now; withdrawing it is a separate approval." }, "unusedUnavailable": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "hyperliquid", "polymarket" ] }, "description": "Venues whose unused money could not be read; unavailable never means zero." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "boughtAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "killCondition": { "type": "string", "minLength": 1, "maxLength": 300 }, "cashKeptUsdc": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "What the basket keeps back as cash in the agent wallet; it is not spent." }, "steps": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many steps the basket's one approval covers, funding moves included." }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the owner approved the basket with one signature; null before then." }, "holdings": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "theme": { "type": "string", "minLength": 1, "maxLength": 60 }, "venue": { "type": "string", "enum": [ "intents", "perps", "polymarket" ], "description": "Where a position is bought: `intents` (crypto and tokenized stocks through NEAR Intents), `perps` (a 1x isolated long or short on Hyperliquid) or `polymarket` (an outcome bought on Polymarket)." }, "instrument": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The instrument's exact id on its venue." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Its short symbol, for display." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Its name, for display." } }, "required": [ "id", "symbol", "name" ] }, "outcome": { "type": "string", "minLength": 1, "maxLength": 100 }, "side": { "type": "string", "enum": [ "buy", "long", "short" ] }, "weightBps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "enum": [ "pending", "bought", "failed", "skipped", "not_bought" ], "description": "Whether the piece that buys this position executed." }, "quantity": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "amount", "unit" ] }, { "type": "null" } ], "description": "What the piece received, from its recorded settlement; null when nothing was." }, "costUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "The USDC the basket's executed pieces paid; null before anything was bought." }, "valueUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "What the bought positions are worth now, at current prices, plus unused venue money; null when nothing was bought or no price is available." }, "changeUsdc": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$" }, { "type": "null" } ], "description": "Value less cost, in USDC; negative for a loss. Null when either is null." }, "priceSource": { "anyOf": [ { "type": "string", "enum": [ "market", "cost" ] }, { "type": "null" } ], "description": "`market` when valued at a current price, `cost` when shown at what it paid because no reviewed price source is available." }, "alsoHeldOutside": { "type": "boolean", "description": "The account holds a different amount of this instrument than the basket bought." }, "linked": { "anyOf": [ { "type": "string", "enum": [ "linked", "finished" ] }, { "type": "null" } ], "description": "Set when the basket's own step did not buy this position and an order stands in for it: `linked` when the user linked an order they placed, `finished` when an approval to finish the basket bought it. Null for a position the basket's own step bought, or one still unbought." } }, "required": [ "index", "theme", "venue", "instrument", "side", "weightBps", "reason", "state", "quantity", "costUsdc", "valueUsdc", "changeUsdc", "priceSource", "alsoHeldOutside", "linked" ] } }, "failures": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "piece": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What the step does, in a few words." }, "outcome": { "type": "string", "enum": [ "failed", "skipped", "not_executed" ] }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300 }, { "type": "null" } ] }, "linkable": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/BasketLinkableOrder" }, "description": "Orders the user placed since the basket's result, for this step's instrument, side and terms, that no basket step holds yet; any of them can be linked to this step. Empty for a step no order can stand in for, such as a funding move." } }, "required": [ "piece", "label", "outcome", "reason", "linkable" ] }, "description": "The buying steps that failed or were skipped, and why. A step linked to an order leaves this list." }, "valuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "performance": { "$ref": "#/components/schemas/BasketPerformance" } }, "required": [ "basketId", "title", "idea", "status", "revision", "budgetUsdc", "costUsdc", "valueUsdc", "changeUsdc", "allocation", "venues", "unused", "unusedUnavailable", "createdAt", "boughtAt", "killCondition", "cashKeptUsdc", "steps", "approvedAt", "holdings", "failures", "valuedAt", "performance" ] }, "BasketLinkableOrder": { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id; pass it to link the order to the step." }, "quantity": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "amount", "unit" ], "description": "What the order received: contracts of a perps market, or shares of an outcome." }, "costUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "What it paid in USDC at its fill price; null when no price was recorded." }, "placedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "operationId", "quantity", "costUsdc", "placedAt" ] }, "BasketPerformance": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "estimate", "actual" ] }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "chartPeriod": { "type": "string", "enum": [ "7d", "since_bought" ] }, "returnPctDecimal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "Percentage units: 4.2 means +4.2%, not 0.042. Null when coverage is incomplete." }, "points": { "maxItems": 9, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "returnPctDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$" } }, "required": [ "at", "returnPctDecimal" ] } }, "positions": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "returnPctDecimal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ] }, "leverageDecimal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "stored_token_closes", "hyperliquid_candles", "polymarket_clob", "basket_valuation" ] } }, "required": [ "index", "returnPctDecimal", "leverageDecimal", "source" ] } }, "fundingIncluded": { "type": "boolean", "description": "Actual inherits the valuation's recorded funding; estimates exclude funding." }, "feesIncluded": { "type": "boolean", "description": "Actual inherits recorded costs and fees; estimates exclude fees." } }, "required": [ "mode", "asOf", "startAt", "endAt", "chartPeriod", "returnPctDecimal", "points", "positions", "fundingIncluded", "feesIncluded" ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Delete a basket 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. `DELETE /v1/users/{userId}/baskets/{basketId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "basketId", "required": true, "description": "The basket's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request DELETE 'https://api.example.test/v1/users/YOUR_USER_ID/baskets/YOUR_BASKET_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 204 The basket is deleted. ```json { "description": "The basket is deleted." } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `basket_buying` — the basket is still buying, so it cannot be deleted yet; try again once its result is in - `basket_awaiting_approval` — an approval to buy this basket is still open; decline it in the chat, then delete the basket ```json { "description": "The operation lost to the current state.\n\n- `basket_buying` — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` — an approval to buy this basket is still open; decline it in the chat, then delete the basket", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "baskets.delete", "summary": "Delete a basket", "tags": [ "baskets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "basketId", "required": true, "description": "The basket's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "204": { "description": "The basket is deleted." }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `basket_buying` — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` — an approval to buy this basket is still open; decline it in the chat, then delete the basket", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Link an order to a basket step 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`). `POST /v1/users/{userId}/baskets/{basketId}/links` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "basketId", "required": true, "description": "The basket's id." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasketLinkInputInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/baskets/YOUR_BASKET_ID/links' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The basket with the order in the step's place. ```json { "description": "The basket with the order in the step's place.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Basket" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted - `basket_order_not_linkable` — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `basket_order_not_linkable` — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `baskets_disabled` — idea baskets are not turned on for this user; hide the Ideas pages and their baskets ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `baskets_disabled` — idea baskets are not turned on for this user; hide the Ideas pages and their baskets", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `basket_step_not_failed` — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again - `basket_step_linked` — another order is already linked to this step; a link is permanent, so read the basket again ```json { "description": "The operation lost to the current state.\n\n- `basket_step_not_failed` — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` — another order is already linked to this step; a link is permanent, so read the basket again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "baskets.link", "summary": "Link an order to a basket step", "tags": [ "baskets" ], "description": "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`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasketLinkInputInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "basketId", "required": true, "description": "The basket's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The basket with the order in the step's place.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Basket" } } } }, "400": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `basket_order_not_linkable` — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `baskets_disabled` — idea baskets are not turned on for this user; hide the Ideas pages and their baskets", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `basket_step_not_failed` — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` — another order is already linked to this step; a link is permanent, so read the basket again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "BasketLinkInputInput": { "type": "object", "properties": { "piece": { "type": "integer", "minimum": 0, "maximum": 5, "description": "The step that did not buy, as `failures[].piece` names it." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order to link, as one of that step's `failures[].linkable[].operationId`." } }, "required": [ "piece", "operationId" ], "additionalProperties": false }, "Basket": { "type": "object", "properties": { "basketId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "idea": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "type": "string", "enum": [ "draft", "buying", "bought", "partly_bought", "not_bought" ], "description": "`draft`: proposed, not bought. `buying`: approved and its pieces are running. `bought`: every piece done, or every step that did not buy later linked to an order that stands in for it. `partly_bought`: some pieces done, others failed or skipped. `not_bought`: approved but nothing was bought, or the approval was declined or expired." }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The latest revision, or the one bought." }, "budgetUsdc": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, "costUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "The USDC the basket's executed pieces paid; null before anything was bought." }, "valueUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "What the bought positions are worth now, at current prices, plus unused venue money; null when nothing was bought or no price is available." }, "changeUsdc": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$" }, { "type": "null" } ], "description": "Value less cost, in USDC; negative for a loss. Null when either is null." }, "allocation": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "theme": { "type": "string", "minLength": 1, "maxLength": 60 }, "weightBps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "theme", "weightBps" ] }, "description": "The basket's themes and their shares, in basis points." }, "venues": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "intents", "perps", "polymarket" ], "description": "Where a position is bought: `intents` (crypto and tokenized stocks through NEAR Intents), `perps` (a 1x isolated long or short on Hyperliquid) or `polymarket` (an outcome bought on Polymarket)." } }, "unused": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "venue": { "type": "string", "enum": [ "hyperliquid", "polymarket" ] }, "amountUsdc": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, "withdrawTool": { "type": "string", "enum": [ "perps_withdraw", "prediction_withdraw" ] } }, "required": [ "venue", "amountUsdc", "withdrawTool" ] }, "description": "Money a funding step moved to a venue that no order used, capped by what the venue holds now; withdrawing it is a separate approval." }, "unusedUnavailable": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "hyperliquid", "polymarket" ] }, "description": "Venues whose unused money could not be read; unavailable never means zero." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "boughtAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "killCondition": { "type": "string", "minLength": 1, "maxLength": 300 }, "cashKeptUsdc": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "What the basket keeps back as cash in the agent wallet; it is not spent." }, "steps": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "How many steps the basket's one approval covers, funding moves included." }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the owner approved the basket with one signature; null before then." }, "holdings": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "theme": { "type": "string", "minLength": 1, "maxLength": 60 }, "venue": { "type": "string", "enum": [ "intents", "perps", "polymarket" ], "description": "Where a position is bought: `intents` (crypto and tokenized stocks through NEAR Intents), `perps` (a 1x isolated long or short on Hyperliquid) or `polymarket` (an outcome bought on Polymarket)." }, "instrument": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The instrument's exact id on its venue." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Its short symbol, for display." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Its name, for display." } }, "required": [ "id", "symbol", "name" ] }, "outcome": { "type": "string", "minLength": 1, "maxLength": 100 }, "side": { "type": "string", "enum": [ "buy", "long", "short" ] }, "weightBps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "enum": [ "pending", "bought", "failed", "skipped", "not_bought" ], "description": "Whether the piece that buys this position executed." }, "quantity": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "amount", "unit" ] }, { "type": "null" } ], "description": "What the piece received, from its recorded settlement; null when nothing was." }, "costUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "The USDC the basket's executed pieces paid; null before anything was bought." }, "valueUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "What the bought positions are worth now, at current prices, plus unused venue money; null when nothing was bought or no price is available." }, "changeUsdc": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$" }, { "type": "null" } ], "description": "Value less cost, in USDC; negative for a loss. Null when either is null." }, "priceSource": { "anyOf": [ { "type": "string", "enum": [ "market", "cost" ] }, { "type": "null" } ], "description": "`market` when valued at a current price, `cost` when shown at what it paid because no reviewed price source is available." }, "alsoHeldOutside": { "type": "boolean", "description": "The account holds a different amount of this instrument than the basket bought." }, "linked": { "anyOf": [ { "type": "string", "enum": [ "linked", "finished" ] }, { "type": "null" } ], "description": "Set when the basket's own step did not buy this position and an order stands in for it: `linked` when the user linked an order they placed, `finished` when an approval to finish the basket bought it. Null for a position the basket's own step bought, or one still unbought." } }, "required": [ "index", "theme", "venue", "instrument", "side", "weightBps", "reason", "state", "quantity", "costUsdc", "valueUsdc", "changeUsdc", "priceSource", "alsoHeldOutside", "linked" ] } }, "failures": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "piece": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What the step does, in a few words." }, "outcome": { "type": "string", "enum": [ "failed", "skipped", "not_executed" ] }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300 }, { "type": "null" } ] }, "linkable": { "maxItems": 10, "type": "array", "items": { "$ref": "#/components/schemas/BasketLinkableOrder" }, "description": "Orders the user placed since the basket's result, for this step's instrument, side and terms, that no basket step holds yet; any of them can be linked to this step. Empty for a step no order can stand in for, such as a funding move." } }, "required": [ "piece", "label", "outcome", "reason", "linkable" ] }, "description": "The buying steps that failed or were skipped, and why. A step linked to an order leaves this list." }, "valuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "performance": { "$ref": "#/components/schemas/BasketPerformance" } }, "required": [ "basketId", "title", "idea", "status", "revision", "budgetUsdc", "costUsdc", "valueUsdc", "changeUsdc", "allocation", "venues", "unused", "unusedUnavailable", "createdAt", "boughtAt", "killCondition", "cashKeptUsdc", "steps", "approvedAt", "holdings", "failures", "valuedAt", "performance" ] }, "BasketLinkableOrder": { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id; pass it to link the order to the step." }, "quantity": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "amount", "unit" ], "description": "What the order received: contracts of a perps market, or shares of an outcome." }, "costUsdc": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(\\.\\d{1,6})?$", "description": "An exact USDC amount as a decimal string with at most six fraction digits." }, { "type": "null" } ], "description": "What it paid in USDC at its fill price; null when no price was recorded." }, "placedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "operationId", "quantity", "costUsdc", "placedAt" ] }, "BasketPerformance": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "estimate", "actual" ] }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "chartPeriod": { "type": "string", "enum": [ "7d", "since_bought" ] }, "returnPctDecimal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "Percentage units: 4.2 means +4.2%, not 0.042. Null when coverage is incomplete." }, "points": { "maxItems": 9, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "returnPctDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$" } }, "required": [ "at", "returnPctDecimal" ] } }, "positions": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "returnPctDecimal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ] }, "leverageDecimal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "stored_token_closes", "hyperliquid_candles", "polymarket_clob", "basket_valuation" ] } }, "required": [ "index", "returnPctDecimal", "leverageDecimal", "source" ] } }, "fundingIncluded": { "type": "boolean", "description": "Actual inherits the valuation's recorded funding; estimates exclude funding." }, "feesIncluded": { "type": "boolean", "description": "Actual inherits recorded costs and fees; estimates exclude fees." } }, "required": [ "mode", "asOf", "startAt", "endAt", "chartPeriod", "returnPctDecimal", "points", "positions", "fundingIncluded", "feesIncluded" ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Create a user 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). `POST /v1/users` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your identifier for this user: unique within your partner, 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. It appears in URLs, so never use an email address or other personal data." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The user's name, for display only." } }, "required": [ "userId", "name" ], "additionalProperties": false } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The user and their agent, with their agent wallet once they have created it. ```json { "description": "The user and their agent, with their agent wallet once they have created it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your identifier for this user: unique within your partner, 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. It appears in URLs, so never use an email address or other personal data." }, "partnerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Your partner id, from your API key." }, "name": { "type": "string", "description": "The user's display name." }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's agent. Every call returns the same one." }, "walletId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The agent wallet's id; null until the user creates it with their signature (Create the agent wallet)." } }, "required": [ "userId", "partnerId", "name", "agentId", "walletId" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "users.create", "summary": "Create a user", "tags": [ "users" ], "description": "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).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your identifier for this user: unique within your partner, 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. It appears in URLs, so never use an email address or other personal data." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The user's name, for display only." } }, "required": [ "userId", "name" ], "additionalProperties": false } } } }, "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The user and their agent, with their agent wallet once they have created it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your identifier for this user: unique within your partner, 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. It appears in URLs, so never use an email address or other personal data." }, "partnerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Your partner id, from your API key." }, "name": { "type": "string", "description": "The user's display name." }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's agent. Every call returns the same one." }, "walletId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The agent wallet's id; null until the user creates it with their signature (Create the agent wallet)." } }, "required": [ "userId", "partnerId", "name", "agentId", "walletId" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInputForRegistration" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [] }, "components": { "responses": { "InvalidInputForRegistration": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # Get the signed-in user Returns the user the session token belongs to and when the session expires. Use it to check that a session is still valid. `GET /v1/users/me` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/me' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The signed-in user and their session. ```json { "description": "The signed-in user and their session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "users.me", "summary": "Get the signed-in user", "tags": [ "users" ], "description": "Returns the user the session token belongs to and when the session expires. Use it to check that a session is still valid.", "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The signed-in user and their session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [] }, "components": { "schemas": { "User": { "type": "object", "properties": { "userId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your identifier for this user: unique within your partner, 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. It appears in URLs, so never use an email address or other personal data." }, "partnerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Your partner id, from your API key." }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's agent." }, "sessionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This session's id; Revoke a session signs it out." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The id of the wallet or passkey the user signed in with." }, "name": { "type": "string", "description": "The user's display name." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this session expires (UTC)." } }, "required": [ "userId", "partnerId", "agentId", "sessionId", "controllerId", "name", "expiresAt" ], "description": "The signed-in user, their agent and the session the token belongs to." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Start wallet sign-in 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. `POST /v1/users/{userId}/session-challenges` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "controller": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "An externally owned EVM signing account.", "enum": [ "evm" ] }, "chainId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The EIP-155 chain identifier included in the login proof." }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "The wallet's EVM address. It is not the agent wallet." } }, "required": [ "kind", "chainId", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A registered P-256 (ES256) or Ed25519 (EdDSA) WebAuthn passkey.", "enum": [ "webauthn" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The credential identifier encoded as base64url." }, "publicKey": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The credential's COSE public key encoded as base64url." }, "rpId": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The trusted relying-party hostname registered for this partner." }, "origin": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The exact trusted browser origin for the credential." } }, "required": [ "kind", "credentialId", "publicKey", "rpId", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A NEAR account. Any of its full-access keys may sign (NEP-413); an implicit account's key is its id.", "enum": [ "near" ] }, "accountId": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^(([a-z\\d]+[-_])*[a-z\\d]+\\.)*([a-z\\d]+[-_])*[a-z\\d]+$", "description": "The NEAR account id, lowercase." } }, "required": [ "kind", "accountId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Solana wallet that signs messages (signMessage).", "enum": [ "solana" ] }, "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The base58 Ed25519 public key that is the Solana address." } }, "required": [ "kind", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Stellar account that signs messages (SEP-53).", "enum": [ "stellar" ] }, "address": { "type": "string", "pattern": "^G[A-Z2-7]{55}$", "description": "The Stellar account id (G… strkey)." } }, "required": [ "kind", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TON wallet that signs text through TON Connect `signData`. The wallet address arrives with each signature.", "enum": [ "ton" ] }, "publicKey": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The wallet's Ed25519 public key in lowercase hexadecimal." } }, "required": [ "kind", "publicKey" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Tron account that signs messages (TIP-191).", "enum": [ "tron" ] }, "address": { "type": "string", "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$", "description": "The base58check Tron address (T…)." } }, "required": [ "kind", "address" ], "additionalProperties": false } ], "description": "The wallet or passkey the user will sign with." }, "origin": { "type": "string", "format": "uri", "description": "The browser origin the user signs in from; one of your registered app origins." }, "createWallet": { "description": "Send `true` to open the account in one signature: for a user with no agent wallet yet, the message also creates it, so after Create a session you send the same `challengeId` and `signature` to Create the agent wallet as `signIn` and the user signs nothing more. A user who already has a wallet gets the plain sign-in message. Leave it out to keep sign-in and wallet creation as two signatures.", "type": "boolean" } }, "required": [ "controller", "origin" ], "additionalProperties": false } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/session-challenges' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The message to sign. ```json { "description": "The message to sign.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This challenge's id; send it with the signature to Create a session." }, "message": { "type": "string", "description": "The message the user signs, exactly as returned." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the challenge expires (UTC); sign and send it before then." }, "recipient": { "description": "NEAR wallets only: the NEP-413 `recipient` to pass to `signMessage`.", "type": "string" }, "createsWallet": { "type": "boolean", "description": "Whether signing this message also creates the user's agent wallet. True only when you sent `createWallet` and the user has no wallet yet: after Create a session, send the same `challengeId` and `signature` to Create the agent wallet as `signIn`." } }, "required": [ "challengeId", "message", "expiresAt", "createsWallet" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "users.sessionChallenge", "summary": "Start wallet sign-in", "tags": [ "users" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "controller": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "An externally owned EVM signing account.", "enum": [ "evm" ] }, "chainId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The EIP-155 chain identifier included in the login proof." }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "The wallet's EVM address. It is not the agent wallet." } }, "required": [ "kind", "chainId", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A registered P-256 (ES256) or Ed25519 (EdDSA) WebAuthn passkey.", "enum": [ "webauthn" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The credential identifier encoded as base64url." }, "publicKey": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The credential's COSE public key encoded as base64url." }, "rpId": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The trusted relying-party hostname registered for this partner." }, "origin": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The exact trusted browser origin for the credential." } }, "required": [ "kind", "credentialId", "publicKey", "rpId", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A NEAR account. Any of its full-access keys may sign (NEP-413); an implicit account's key is its id.", "enum": [ "near" ] }, "accountId": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^(([a-z\\d]+[-_])*[a-z\\d]+\\.)*([a-z\\d]+[-_])*[a-z\\d]+$", "description": "The NEAR account id, lowercase." } }, "required": [ "kind", "accountId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Solana wallet that signs messages (signMessage).", "enum": [ "solana" ] }, "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The base58 Ed25519 public key that is the Solana address." } }, "required": [ "kind", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Stellar account that signs messages (SEP-53).", "enum": [ "stellar" ] }, "address": { "type": "string", "pattern": "^G[A-Z2-7]{55}$", "description": "The Stellar account id (G… strkey)." } }, "required": [ "kind", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TON wallet that signs text through TON Connect `signData`. The wallet address arrives with each signature.", "enum": [ "ton" ] }, "publicKey": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The wallet's Ed25519 public key in lowercase hexadecimal." } }, "required": [ "kind", "publicKey" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Tron account that signs messages (TIP-191).", "enum": [ "tron" ] }, "address": { "type": "string", "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$", "description": "The base58check Tron address (T…)." } }, "required": [ "kind", "address" ], "additionalProperties": false } ], "description": "The wallet or passkey the user will sign with." }, "origin": { "type": "string", "format": "uri", "description": "The browser origin the user signs in from; one of your registered app origins." }, "createWallet": { "description": "Send `true` to open the account in one signature: for a user with no agent wallet yet, the message also creates it, so after Create a session you send the same `challengeId` and `signature` to Create the agent wallet as `signIn` and the user signs nothing more. A user who already has a wallet gets the plain sign-in message. Leave it out to keep sign-in and wallet creation as two signatures.", "type": "boolean" } }, "required": [ "controller", "origin" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The message to sign.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This challenge's id; send it with the signature to Create a session." }, "message": { "type": "string", "description": "The message the user signs, exactly as returned." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the challenge expires (UTC); sign and send it before then." }, "recipient": { "description": "NEAR wallets only: the NEP-413 `recipient` to pass to `signMessage`.", "type": "string" }, "createsWallet": { "type": "boolean", "description": "Whether signing this message also creates the user's agent wallet. True only when you sent `createWallet` and the user has no wallet yet: after Create a session, send the same `challengeId` and `signature` to Create the agent wallet as `signIn`." } }, "required": [ "challengeId", "message", "expiresAt", "createsWallet" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInputForRegistration" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInputForRegistration": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # Create a session 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. `POST /v1/users/{userId}/sessions` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "controller": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "An externally owned EVM signing account.", "enum": [ "evm" ] }, "chainId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The EIP-155 chain identifier included in the login proof." }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "The wallet's EVM address. It is not the agent wallet." } }, "required": [ "kind", "chainId", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A registered P-256 (ES256) or Ed25519 (EdDSA) WebAuthn passkey.", "enum": [ "webauthn" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The credential identifier encoded as base64url." }, "publicKey": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The credential's COSE public key encoded as base64url." }, "rpId": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The trusted relying-party hostname registered for this partner." }, "origin": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The exact trusted browser origin for the credential." } }, "required": [ "kind", "credentialId", "publicKey", "rpId", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A NEAR account. Any of its full-access keys may sign (NEP-413); an implicit account's key is its id.", "enum": [ "near" ] }, "accountId": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^(([a-z\\d]+[-_])*[a-z\\d]+\\.)*([a-z\\d]+[-_])*[a-z\\d]+$", "description": "The NEAR account id, lowercase." } }, "required": [ "kind", "accountId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Solana wallet that signs messages (signMessage).", "enum": [ "solana" ] }, "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The base58 Ed25519 public key that is the Solana address." } }, "required": [ "kind", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Stellar account that signs messages (SEP-53).", "enum": [ "stellar" ] }, "address": { "type": "string", "pattern": "^G[A-Z2-7]{55}$", "description": "The Stellar account id (G… strkey)." } }, "required": [ "kind", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TON wallet that signs text through TON Connect `signData`. The wallet address arrives with each signature.", "enum": [ "ton" ] }, "publicKey": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The wallet's Ed25519 public key in lowercase hexadecimal." } }, "required": [ "kind", "publicKey" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Tron account that signs messages (TIP-191).", "enum": [ "tron" ] }, "address": { "type": "string", "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$", "description": "The base58check Tron address (T…)." } }, "required": [ "kind", "address" ], "additionalProperties": false } ], "description": "The wallet or passkey your login verified. The user's first session registers it for good: later sessions must name the same one, and it signs the user's withdrawals and approvals." }, "createWallet": { "description": "Send `true` when the user just created this passkey in your app, to open their account with no signature: if this session is the one that registers the passkey and the user has no agent wallet, the answer has `createsWallet: true`, and Create the agent wallet with an empty body from this session makes the wallet within 270 seconds. Creating a passkey signs nothing, so this is the one sign-up the user confirms only once. A wallet, a passkey already registered, or one whose key is no point on its curve opens nothing this way (`createsWallet: false`): the user signs the wallet's creation.", "type": "boolean" } }, "required": [ "controller" ], "additionalProperties": false, "description": "Your app's own login already signed the user in (for example near.com's 1Click session): name the wallet or passkey it verified. No signature is needed." }, { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `challengeId` from Start wallet sign-in." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "An EIP-191 personal-message signature by the current controller.", "enum": [ "evm" ] }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A user-verified WebAuthn assertion over the message digest.", "enum": [ "webauthn" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience.", "enum": [ "near" ] }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes.", "enum": [ "solana" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message).", "enum": [ "stellar" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message.", "enum": [ "ton" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TIP-191 `signMessageV2` signature over the exact message.", "enum": [ "tron" ] }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the challenge `message`." } }, "required": [ "challengeId", "signature" ], "additionalProperties": false, "description": "Wallet sign-in: the user signed the message from Start wallet sign-in. Use this when your app has no sign-in of its own." } ], "description": "How the user signed in: through your app's own login, or with a wallet signature." } } }, "description": "How the user signed in: through your app's own login, or with a wallet signature." } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/sessions' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 201 The session and its token, shown only this once. ```json { "description": "The session and its token, shown only this once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^fin_session_[A-Za-z0-9_-]{43}$", "description": "The session token, shown only once. Send it as `Authorization: Bearer …`; keep it on your server or in an HttpOnly cookie." }, "session": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The session's id; Revoke a session signs it out." }, "partnerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Your partner id." }, "userId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your identifier for this user: unique within your partner, 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. It appears in URLs, so never use an email address or other personal data." }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's agent." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The id of the wallet or passkey the user signed in with." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the session expires (UTC). Create a new session after that." } }, "required": [ "id", "partnerId", "userId", "agentId", "controllerId", "expiresAt" ], "description": "The session: its id, user and expiry." }, "createsWallet": { "type": "boolean", "description": "Whether this session opened the user's account, so their agent wallet needs no further signature from them. After a wallet sign-in, true when the challenge had `createsWallet: true`: send its `challengeId` and `signature` to Create the agent wallet as `signIn`. After your app's own login with `createWallet`, true for a passkey this session registered: send Create the agent wallet an empty body from this session within 270 seconds. Otherwise false." } }, "required": [ "token", "session", "createsWallet" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "users.createSession", "summary": "Create a session", "tags": [ "users" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "controller": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "An externally owned EVM signing account.", "enum": [ "evm" ] }, "chainId": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The EIP-155 chain identifier included in the login proof." }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "The wallet's EVM address. It is not the agent wallet." } }, "required": [ "kind", "chainId", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A registered P-256 (ES256) or Ed25519 (EdDSA) WebAuthn passkey.", "enum": [ "webauthn" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The credential identifier encoded as base64url." }, "publicKey": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The credential's COSE public key encoded as base64url." }, "rpId": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The trusted relying-party hostname registered for this partner." }, "origin": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The exact trusted browser origin for the credential." } }, "required": [ "kind", "credentialId", "publicKey", "rpId", "origin" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A NEAR account. Any of its full-access keys may sign (NEP-413); an implicit account's key is its id.", "enum": [ "near" ] }, "accountId": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^(([a-z\\d]+[-_])*[a-z\\d]+\\.)*([a-z\\d]+[-_])*[a-z\\d]+$", "description": "The NEAR account id, lowercase." } }, "required": [ "kind", "accountId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Solana wallet that signs messages (signMessage).", "enum": [ "solana" ] }, "address": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The base58 Ed25519 public key that is the Solana address." } }, "required": [ "kind", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Stellar account that signs messages (SEP-53).", "enum": [ "stellar" ] }, "address": { "type": "string", "pattern": "^G[A-Z2-7]{55}$", "description": "The Stellar account id (G… strkey)." } }, "required": [ "kind", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TON wallet that signs text through TON Connect `signData`. The wallet address arrives with each signature.", "enum": [ "ton" ] }, "publicKey": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The wallet's Ed25519 public key in lowercase hexadecimal." } }, "required": [ "kind", "publicKey" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Tron account that signs messages (TIP-191).", "enum": [ "tron" ] }, "address": { "type": "string", "pattern": "^T[1-9A-HJ-NP-Za-km-z]{33}$", "description": "The base58check Tron address (T…)." } }, "required": [ "kind", "address" ], "additionalProperties": false } ], "description": "The wallet or passkey your login verified. The user's first session registers it for good: later sessions must name the same one, and it signs the user's withdrawals and approvals." }, "createWallet": { "description": "Send `true` when the user just created this passkey in your app, to open their account with no signature: if this session is the one that registers the passkey and the user has no agent wallet, the answer has `createsWallet: true`, and Create the agent wallet with an empty body from this session makes the wallet within 270 seconds. Creating a passkey signs nothing, so this is the one sign-up the user confirms only once. A wallet, a passkey already registered, or one whose key is no point on its curve opens nothing this way (`createsWallet: false`): the user signs the wallet's creation.", "type": "boolean" } }, "required": [ "controller" ], "additionalProperties": false, "description": "Your app's own login already signed the user in (for example near.com's 1Click session): name the wallet or passkey it verified. No signature is needed." }, { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `challengeId` from Start wallet sign-in." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "An EIP-191 personal-message signature by the current controller.", "enum": [ "evm" ] }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A user-verified WebAuthn assertion over the message digest.", "enum": [ "webauthn" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience.", "enum": [ "near" ] }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes.", "enum": [ "solana" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message).", "enum": [ "stellar" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message.", "enum": [ "ton" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TIP-191 `signMessageV2` signature over the exact message.", "enum": [ "tron" ] }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the challenge `message`." } }, "required": [ "challengeId", "signature" ], "additionalProperties": false, "description": "Wallet sign-in: the user signed the message from Start wallet sign-in. Use this when your app has no sign-in of its own." } ], "description": "How the user signed in: through your app's own login, or with a wallet signature." } } }, "description": "How the user signed in: through your app's own login, or with a wallet signature." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "The session and its token, shown only this once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^fin_session_[A-Za-z0-9_-]{43}$", "description": "The session token, shown only once. Send it as `Authorization: Bearer …`; keep it on your server or in an HttpOnly cookie." }, "session": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The session's id; Revoke a session signs it out." }, "partnerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Your partner id." }, "userId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your identifier for this user: unique within your partner, 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. It appears in URLs, so never use an email address or other personal data." }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's agent." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The id of the wallet or passkey the user signed in with." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the session expires (UTC). Create a new session after that." } }, "required": [ "id", "partnerId", "userId", "agentId", "controllerId", "expiresAt" ], "description": "The session: its id, user and expiry." }, "createsWallet": { "type": "boolean", "description": "Whether this session opened the user's account, so their agent wallet needs no further signature from them. After a wallet sign-in, true when the challenge had `createsWallet: true`: send its `challengeId` and `signature` to Create the agent wallet as `signIn`. After your app's own login with `createWallet`, true for a passkey this session registered: send Create the agent wallet an empty body from this session within 270 seconds. Otherwise false." } }, "required": [ "token", "session", "createsWallet" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInputForRegistration" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "responses": { "InvalidInputForRegistration": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # Revoke a session 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. `DELETE /v1/users/{userId}/sessions/{sessionId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "sessionId", "required": true, "description": "The session to sign out: the `id` from Create a session." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request DELETE 'https://api.example.test/v1/users/YOUR_USER_ID/sessions/YOUR_SESSION_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 204 The session is signed out. ```json { "description": "The session is signed out." } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "users.revokeSession", "summary": "Revoke a session", "tags": [ "users" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "sessionId", "required": true, "description": "The session to sign out: the `id` from Create a session." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "204": { "description": "The session is signed out." }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List a user's features 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 /v1/users/{userId}/features` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/features' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 Every feature and whether this user has it. ```json { "description": "Every feature and whether this user has it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFeatures" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "users.listFeatures", "summary": "List a user's features", "tags": [ "users" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "Every feature and whether this user has it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFeatures" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "UserFeatures": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserFeature" }, "description": "Every feature, each once." } }, "required": [ "data" ], "description": "The features an operator turns on or off for each user, and this user's." }, "UserFeature": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "limit_orders", "market_research", "push_exit_monitoring", "perps", "perps_api_wallet", "tokenized_stocks", "earn", "steering", "prediction", "notifications", "solana", "voice", "agent_api_wallets", "baskets", "news_exits", "news_home", "grid_trading", "funded_orders", "feed_extension", "proactive", "cash_outs", "coin_funding" ], "description": "The feature:\n- `limit_orders`: Placing new resting limit orders. Reading and cancelling orders are never gated.\n- `market_research`: Research in chat from the market desk: its market read, liquidity map and narratives, price history, news, prediction markets, derivatives, sentiment, macro and protocol data, project profiles, fundraising and research.\n- `push_exit_monitoring`: Push price feeds as an extra exit trigger on new automations, checked when one is previewed or saved.\n- `perps`: Opening, reading, funding and trading the agent's own Hyperliquid perpetual futures account.\n- `perps_api_wallet`: Sign the agent's Hyperliquid orders, cancels and margin changes with an approved API wallet instead of the account key.\n- `tokenized_stocks`: Buying and selling Ondo's tokenized U.S. stocks and ETFs, where the user's country allows them.\n- `earn`: Depositing into near.com's curated yield vaults. Withdrawing from a vault is never gated.\n- `steering`: Sending a message to a run that is still working, so the agent reads it at its next step.\n- `prediction`: Opening, reading, funding and exact approved orders on the agent's own Polymarket account.\n- `notifications`: Lets fin promise a ping on the person's devices, where their app delivers one.\n- `solana`: Buying any Solana token through the agent's own Solana account, and finding memecoins. Selling and withdrawing are never gated.\n- `voice`: Talking instead of typing: one short recording turned into text in the message box, on the deployment's own model provider.\n- `agent_api_wallets`: New agent wallets set up through the NEAR Intents Agent API, owned by the user's own wallet or passkey, for users whose app reads the wallet's `intentsAccount`.\n- `baskets`: Turning an idea into a basket of positions across venues, bought with one approval and one signature.\n- `news_exits`: Closing a perps position when the news shows what its owner described in their own words.\n- `news_home`: The fin app's news-first Home: a token ticker, the market's top stories and latest moves, and the balance with its four actions in the sidebar.\n- `grid_trading`: Starting and resuming grids of resting limit orders. Reading, pausing and cancelling a grid are never gated.\n- `funded_orders`: One approval that funds a Polymarket buy's or a Hyperliquid perps order's shortfall, then places the order.\n- `feed_extension`: Experimental feed extension pages and post handoff.\n- `proactive`: fin pings about big news and big moves in what the person holds and looks over their week, with options; in chat, an answer about the news ends with ways to act on it.\n- `cash_outs`: One approval that closes a perps position or sells Polymarket shares, then brings what that freed home.\n- `coin_funding`: A one-shot venue funding paid from a coin of the agent wallet (NEAR, ETH, BTC and the other reviewed coins) under its one signature." }, "enabled": { "type": "boolean", "description": "Whether the user has the feature now." } }, "required": [ "feature", "enabled" ], "description": "A feature and whether this user has it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get the main conversation 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. `GET /v1/users/{userId}/conversations/main` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/conversations/main' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The main conversation. ```json { "description": "The main conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "conversations.main", "summary": "Get the main conversation", "tags": [ "conversations" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The main conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "title": { "description": "The conversation's title, or null if none was set.", "type": [ "string", "null" ] }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "Where this conversation came from: an ordinary conversation, or one an automation started." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the conversation was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the conversation was last modified." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user deleted the conversation; null while it exists. A deleted conversation stays readable but takes no new messages." }, "summary": { "type": "object", "properties": { "runStatus": { "anyOf": [ { "type": "string", "const": "idle" }, { "$ref": "#/components/schemas/RunStatus" } ], "description": "What the last run is doing: `idle` before any run, `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals in this conversation are waiting on the user." }, "userMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the user has sent in this conversation." }, "assistantMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the assistant has sent in this conversation." }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many tool calls the conversation's runs have made." }, "lastEventAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the last event was saved; null before the first." }, "lastUserText": { "description": "The user's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastAssistantText": { "description": "The assistant's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastRunError": { "description": "The last run's failure message, when its most recent run failed.", "type": [ "string", "null" ] } }, "required": [ "runStatus", "pendingApprovals", "userMessages", "assistantMessages", "toolCalls", "lastEventAt", "lastUserText", "lastAssistantText", "lastRunError" ], "description": "The conversation's current status and a preview of its latest messages." } }, "required": [ "id", "title", "origin", "createdAt", "updatedAt", "deletedAt", "summary" ], "description": "One conversation: its title, origin, and a live summary of its last run." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Create a conversation 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. `POST /v1/users/{userId}/conversations` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": false, "description": "Optional. A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. Without it, a retry creates a second one." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "default": {}, "type": "object", "properties": { "title": { "description": "A title for the conversation; omit to leave it untitled.", "type": "string", "maxLength": 120 } }, "additionalProperties": false } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/conversations' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{}' ``` ## Responses ### 201 The new conversation; the same conversation again when this `Idempotency-Key` already created one. ```json { "description": "The new conversation; the same conversation again when this `Idempotency-Key` already created one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "conversations.create", "summary": "Create a conversation", "tags": [ "conversations" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "default": {}, "type": "object", "properties": { "title": { "description": "A title for the conversation; omit to leave it untitled.", "type": "string", "maxLength": 120 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": false, "description": "Optional. A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. Without it, a retry creates a second one." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "201": { "description": "The new conversation; the same conversation again when this `Idempotency-Key` already created one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "title": { "description": "The conversation's title, or null if none was set.", "type": [ "string", "null" ] }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "Where this conversation came from: an ordinary conversation, or one an automation started." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the conversation was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the conversation was last modified." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user deleted the conversation; null while it exists. A deleted conversation stays readable but takes no new messages." }, "summary": { "type": "object", "properties": { "runStatus": { "anyOf": [ { "type": "string", "const": "idle" }, { "$ref": "#/components/schemas/RunStatus" } ], "description": "What the last run is doing: `idle` before any run, `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals in this conversation are waiting on the user." }, "userMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the user has sent in this conversation." }, "assistantMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the assistant has sent in this conversation." }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many tool calls the conversation's runs have made." }, "lastEventAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the last event was saved; null before the first." }, "lastUserText": { "description": "The user's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastAssistantText": { "description": "The assistant's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastRunError": { "description": "The last run's failure message, when its most recent run failed.", "type": [ "string", "null" ] } }, "required": [ "runStatus", "pendingApprovals", "userMessages", "assistantMessages", "toolCalls", "lastEventAt", "lastUserText", "lastAssistantText", "lastRunError" ], "description": "The conversation's current status and a preview of its latest messages." } }, "required": [ "id", "title", "origin", "createdAt", "updatedAt", "deletedAt", "summary" ], "description": "One conversation: its title, origin, and a live summary of its last run." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List conversations 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 /v1/users/{userId}/conversations` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "default": "conversation", "type": "string", "enum": [ "conversation", "automation", "all" ] }, "in": "query", "name": "origin", "required": false, "description": "Which conversations: `conversation` (the default) for chats the user started, `automation` for those automations started, `all` for both." }, { "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "inactive" ] }, "in": "query", "name": "activity", "required": false, "description": "`active` keeps conversations with a run in progress or an approval waiting, `inactive` the rest; `all` (the default) keeps both." }, { "schema": { "default": "created", "type": "string", "enum": [ "created", "recent" ] }, "in": "query", "name": "order", "required": false, "description": "`created` (the default) sorts newest first by creation; `recent` by latest activity, where a conversation with none counts from its creation." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/conversations' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of the caller's conversations. ```json { "description": "A page of the caller's conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "conversations.list", "summary": "List conversations", "tags": [ "conversations" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "default": "conversation", "type": "string", "enum": [ "conversation", "automation", "all" ] }, "in": "query", "name": "origin", "required": false, "description": "Which conversations: `conversation` (the default) for chats the user started, `automation` for those automations started, `all` for both." }, { "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "inactive" ] }, "in": "query", "name": "activity", "required": false, "description": "`active` keeps conversations with a run in progress or an approval waiting, `inactive` the rest; `all` (the default) keeps both." }, { "schema": { "default": "created", "type": "string", "enum": [ "created", "recent" ] }, "in": "query", "name": "order", "required": false, "description": "`created` (the default) sorts newest first by creation; `recent` by latest activity, where a conversation with none counts from its creation." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of the caller's conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "title": { "description": "The conversation's title, or null if none was set.", "type": [ "string", "null" ] }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "Where this conversation came from: an ordinary conversation, or one an automation started." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the conversation was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the conversation was last modified." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user deleted the conversation; null while it exists. A deleted conversation stays readable but takes no new messages." }, "summary": { "type": "object", "properties": { "runStatus": { "anyOf": [ { "type": "string", "const": "idle" }, { "$ref": "#/components/schemas/RunStatus" } ], "description": "What the last run is doing: `idle` before any run, `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals in this conversation are waiting on the user." }, "userMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the user has sent in this conversation." }, "assistantMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the assistant has sent in this conversation." }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many tool calls the conversation's runs have made." }, "lastEventAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the last event was saved; null before the first." }, "lastUserText": { "description": "The user's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastAssistantText": { "description": "The assistant's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastRunError": { "description": "The last run's failure message, when its most recent run failed.", "type": [ "string", "null" ] } }, "required": [ "runStatus", "pendingApprovals", "userMessages", "assistantMessages", "toolCalls", "lastEventAt", "lastUserText", "lastAssistantText", "lastRunError" ], "description": "The conversation's current status and a preview of its latest messages." } }, "required": [ "id", "title", "origin", "createdAt", "updatedAt", "deletedAt", "summary" ], "description": "One conversation: its title, origin, and a live summary of its last run." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a conversation Returns one conversation with a summary of its latest activity: last messages, run status and waiting approvals. `GET /v1/users/{userId}/conversations/{conversationId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/conversations/YOUR_CONVERSATION_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The conversation. ```json { "description": "The conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "conversations.get", "summary": "Get a conversation", "tags": [ "conversations" ], "description": "Returns one conversation with a summary of its latest activity: last messages, run status and waiting approvals.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "title": { "description": "The conversation's title, or null if none was set.", "type": [ "string", "null" ] }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "Where this conversation came from: an ordinary conversation, or one an automation started." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the conversation was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the conversation was last modified." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user deleted the conversation; null while it exists. A deleted conversation stays readable but takes no new messages." }, "summary": { "type": "object", "properties": { "runStatus": { "anyOf": [ { "type": "string", "const": "idle" }, { "$ref": "#/components/schemas/RunStatus" } ], "description": "What the last run is doing: `idle` before any run, `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals in this conversation are waiting on the user." }, "userMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the user has sent in this conversation." }, "assistantMessages": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many messages the assistant has sent in this conversation." }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many tool calls the conversation's runs have made." }, "lastEventAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the last event was saved; null before the first." }, "lastUserText": { "description": "The user's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastAssistantText": { "description": "The assistant's most recent message, for a list preview; null before the first.", "type": [ "string", "null" ] }, "lastRunError": { "description": "The last run's failure message, when its most recent run failed.", "type": [ "string", "null" ] } }, "required": [ "runStatus", "pendingApprovals", "userMessages", "assistantMessages", "toolCalls", "lastEventAt", "lastUserText", "lastAssistantText", "lastRunError" ], "description": "The conversation's current status and a preview of its latest messages." } }, "required": [ "id", "title", "origin", "createdAt", "updatedAt", "deletedAt", "summary" ], "description": "One conversation: its title, origin, and a live summary of its last run." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Delete a conversation 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. `DELETE /v1/users/{userId}/conversations/{conversationId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request DELETE 'https://api.example.test/v1/users/YOUR_USER_ID/conversations/YOUR_CONVERSATION_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 204 The conversation is deleted. ```json { "description": "The conversation is deleted." } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `run_active` — a run already holds this conversation ```json { "description": "The operation lost to the current state.\n\n- `run_active` — a run already holds this conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "conversations.delete", "summary": "Delete a conversation", "tags": [ "conversations" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "204": { "description": "The conversation is deleted." }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `run_active` — a run already holds this conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List a conversation's events 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. `GET /v1/users/{userId}/conversations/{conversationId}/events` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "An `after` cursor from the previous page; omit to read from the beginning." }, { "schema": { "default": 500, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false, "description": "How many events to answer, at most 1000" } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/conversations/YOUR_CONVERSATION_ID/events' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of the conversation's saved events. ```json { "description": "A page of the conversation's saved events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FinEvent" }, "description": "This page's events, oldest first." }, "nextCursor": { "description": "The cursor for the next page, or null at the end as of this read; a live conversation may append more.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "events.list", "summary": "List a conversation's events", "tags": [ "events" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "An `after` cursor from the previous page; omit to read from the beginning." }, { "schema": { "default": 500, "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "limit", "required": false, "description": "How many events to answer, at most 1000" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of the conversation's saved events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FinEvent" }, "description": "This page's events, oldest first." }, "nextCursor": { "description": "The cursor for the next page, or null at the end as of this read; a live conversation may append more.", "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "FinEvent": { "oneOf": [ { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "run.started", "description": "Identifies this as a `run.started` event." }, "payload": { "type": "object", "properties": { "input": { "type": "string", "description": "The user's message, or the automation's triggering text, that this run processes." }, "origin": { "description": "Which automation triggered this run; absent for an ordinary user turn.", "type": "object", "properties": { "automationId": { "type": "string", "description": "The automation that started this run." }, "name": { "type": "string", "description": "The automation's name at the time it started this run." } }, "required": [ "automationId", "name" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run this event opened, so a client following the stream can name it (to stop it)." } }, "required": [ "input", "runId" ], "description": "The `run.started` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "Opens a new run: the engine admitted it and is about to process the input, whether an ordinary turn or an automation firing. Emitted once, at admission — a run resumed after an approval does not get a second one. `run.ended` closes what this event opened." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "run.ended", "description": "Identifies this as a `run.ended` event." }, "payload": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The admitted root run that reached its terminal state." }, "status": { "type": "string", "enum": [ "completed", "aborted", "failed" ], "description": "The terminal result of the root run; approval waits do not end it." }, "usage": { "description": "Token counts and cost for this run, once its accounting settles.", "type": "object", "properties": { "inputTokens": { "type": "number", "description": "How many input tokens the run consumed." }, "outputTokens": { "type": "number", "description": "How many output tokens the run produced." }, "costCents": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "description": "The run's cost, in whole USD cents." }, "costUncertain": { "type": "boolean", "description": "True when the exact provider cost could not be confirmed and `costCents` is a best-effort estimate." } }, "required": [ "inputTokens", "outputTokens", "costCents", "costUncertain" ] }, "error": { "description": "The run's failure message, present when `status` is `failed`.", "type": "string" }, "failure": { "description": "Structured cause of a failed run: its `code`, `stage` and optional provider detail. Present when `status` is `failed`; absent on runs that failed before this field existed.", "type": "object", "properties": { "code": { "type": "string", "enum": [ "model_timeout", "model_invalid_output", "execution_deadline", "provider_rate_limit", "provider_unavailable", "provider_authentication", "internal_error", "context_too_large", "daily_budget_exhausted", "monthly_budget_exhausted", "budget_frozen", "partner_daily_budget_exhausted", "partner_monthly_budget_exhausted", "unknown" ], "description": "Why the execution failed: `model_timeout` (the model was too slow to respond), `execution_deadline` (the run's active time limit elapsed before it finished), `provider_rate_limit` or `provider_unavailable` (classified from HTTP status or a connection/body-read failure observed by the host), `model_invalid_output` (terminal structured output still failed its required format after bounded repair), `context_too_large` (the request stayed over the model's context window after the host condensed earlier history and retried once), `daily_budget_exhausted`, `monthly_budget_exhausted` or `budget_frozen` (the user's AI budget for the UTC day or month, or an operator's freeze on it, left no room for the run's next model request), `partner_daily_budget_exhausted` or `partner_monthly_budget_exhausted` (the partner account's AI spend limit for the UTC day or month left no room for it), `internal_error` (a host-side fault), or `unknown` when nothing more specific was classified. A budget or spend-limit code means a limit stopped the run, not that the model failed; trying again fails the same way until the limit clears. A raised user budget or a lifted freeze applies at once; a raised partner limit applies from the next UTC day or month, because the open period keeps the cap it started with." }, "stage": { "type": "string", "enum": [ "model_request", "tool_execution", "finalization" ], "description": "Which phase of the run was executing when it failed: `model_request` while calling or awaiting the model provider, `tool_execution` while running or resuming a tool call, or `finalization` while settling the run's output and accounting after the model finished." }, "providerMessage": { "description": "The model provider's own error text, when one was available: credential values are redacted and it is cut to 256 characters, but it is not a content classifier, so other sensitive detail may remain. Treat it as diagnostic context only — never branch on it, and review before showing it to an end user.", "type": "string", "minLength": 1, "maxLength": 256 }, "diagnosticReference": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This failed run's own id, repeated here as one field to cite when asking support to check the host's internal logs for this execution; it carries no meaning beyond that." } }, "required": [ "code", "stage", "diagnosticReference" ] } }, "required": [ "runId", "status" ], "description": "The `run.ended` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The root run reached a terminal state: completed, failed or aborted. Its runId is the same as run.started and every pause/resume. Waiting for approval emits run.paused instead. Accounting includes all continuation segments." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "run.paused", "description": "Identifies this as a `run.paused` event." }, "payload": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The admitted root run, retained across approval waits and continuations." } }, "required": [ "runId" ], "description": "The run is waiting for approval; it has not finished." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The run is waiting for human input or approval. Its identity and original request remain unchanged." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "run.resumed", "description": "Identifies this as a `run.resumed` event." }, "payload": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The same root run that paused." } }, "required": [ "runId" ], "description": "The paused run has resumed after an approval decision." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "An approval decision resumed the same root run. No new instruction or run identity was created." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "run.steered", "description": "Identifies this as a `run.steered` event." }, "payload": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run the message was sent to; it keeps working." }, "steerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The message's id, as the run's `steers` entry names it." }, "text": { "type": "string", "description": "The user's message, as they sent it." } }, "required": [ "runId", "steerId", "text" ], "description": "The `run.steered` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The agent read a message the user sent while the run was working (Steer a run). Emitted at the agent's next step, before its next reply, so it lands in the conversation where the agent saw it; `steerId` matches the run's `steers` entry. Several messages sent within one step each get their own event, in the order sent. The same run continues; a message the run ended before reading never gets one." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "agent.entry", "description": "Identifies this as an `agent.entry` event." }, "payload": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "tool" ], "description": "Who this message is from: `user`, `assistant`, or `tool` for a tool's own display text." }, "text": { "type": "string", "description": "The message's display text." }, "interrupted": { "description": "Present on an assistant draft whose model response did not complete. Preserve it as interrupted even if the run later recovers and completes.", "type": "boolean", "const": true }, "tool": { "description": "Which tool this entry displays the result of; present only when `role` is `tool`.", "type": "object", "properties": { "name": { "type": "string", "description": "The tool's public name." }, "outcome": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "completed", "description": "The tool ran and returned a result." }, "result": { "description": "The tool's own result value." }, "financialFailures": { "description": "Bounded financial failure display evidence. The tool result and spending authority are unchanged.", "type": "object", "properties": { "nodeFailures": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15 }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ] }, "category": { "type": "string", "enum": [ "price_limit", "insufficient_funds", "unavailable", "integrity", "dependency", "expired", "authority", "conflict", "stopped", "request_blocked", "unknown" ] }, "diagnostic": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "quote_floor", "quote_ceiling" ] }, "classification": { "type": "string", "const": "terms" }, "expectedAtomic": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "observedAtomic": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "inputTokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "outputTokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." } }, "required": [ "rule", "classification", "expectedAtomic", "observedAtomic", "inputTokenId", "outputTokenId" ] } }, "required": [ "index", "reason", "category" ] } }, "preflightFailure": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ] }, "index": { "type": "integer", "minimum": 0, "maximum": 15 }, "diagnostic": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "quote_floor", "quote_ceiling" ] }, "classification": { "type": "string", "const": "terms" }, "expectedAtomic": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "observedAtomic": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "inputTokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "outputTokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." } }, "required": [ "rule", "classification", "expectedAtomic", "observedAtomic", "inputTokenId", "outputTokenId" ] } }, "required": [ "reason" ] }, "recoverable": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15 }, "kind": { "type": "string", "enum": [ "unclaimed", "refunded", "not_executed" ] } }, "required": [ "index", "kind" ] } }, "recovery": { "description": "Root operations omit this. A recovery child carries a proved original-action map, or null when no safe map is available; null disables recovery controls.", "anyOf": [ { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "originalIndices": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$" } }, "required": [ "operationId", "originalIndices", "maxValueLossBps" ] }, { "type": "null" } ] } } }, "providerRef": { "description": "The upstream provider's own reference, when it returned one.", "type": "string" } }, "required": [ "status", "result" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "denied", "description": "The call was refused before it ran." }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "denied", "egress_denied", "invalid_input", "execution_failed" ], "description": "Why the tool call did not produce a result: `denied` by policy or the user, `egress_denied` for a network destination the tool cannot reach, `invalid_input` for arguments the tool rejected, or `execution_failed` for a fault while it ran." }, "message": { "type": "string", "description": "A human-readable explanation of the failure." }, "hint": { "description": "A suggestion for what to try instead, when there is one.", "type": "string" }, "recovery": { "type": "string", "enum": [ "wait", "owner", "none" ], "description": "Who can fix the failure: `wait` when the same request may succeed later without anyone acting and nothing was signed or sent, `owner` when it fails the same way until the owner acts (the remedy says how), or `none` when this attempt cannot succeed and neither waiting nor the owner changes that, though a later run may. A failure that names no class is `none`." }, "remedy": { "type": "string", "enum": [ "add_funds", "edit_automation" ], "description": "What the owner does about an `owner` failure: `add_funds` of the asset the action spends or sells, or `edit_automation` to change its terms." }, "retryAfterSeconds": { "description": "For a `wait` failure, how long the failing service asked to wait before the same request is repeated, in whole seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "reference": { "description": "Correlation for diagnosis: the request id, or the workflow id of background work. Never a cause.", "type": "string", "maxLength": 128 } }, "required": [ "code", "message" ], "description": "Why the call was denied." } }, "required": [ "status", "error" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "pending_approval", "description": "The call is parked, waiting on a human decision." }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "summary": { "type": "string", "description": "A short human-readable summary of what approving this would do." } }, "required": [ "status", "approvalId", "summary" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "failed", "description": "The call ran but did not complete successfully." }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "denied", "egress_denied", "invalid_input", "execution_failed" ], "description": "Why the tool call did not produce a result: `denied` by policy or the user, `egress_denied` for a network destination the tool cannot reach, `invalid_input` for arguments the tool rejected, or `execution_failed` for a fault while it ran." }, "message": { "type": "string", "description": "A human-readable explanation of the failure." }, "hint": { "description": "A suggestion for what to try instead, when there is one.", "type": "string" }, "recovery": { "type": "string", "enum": [ "wait", "owner", "none" ], "description": "Who can fix the failure: `wait` when the same request may succeed later without anyone acting and nothing was signed or sent, `owner` when it fails the same way until the owner acts (the remedy says how), or `none` when this attempt cannot succeed and neither waiting nor the owner changes that, though a later run may. A failure that names no class is `none`." }, "remedy": { "type": "string", "enum": [ "add_funds", "edit_automation" ], "description": "What the owner does about an `owner` failure: `add_funds` of the asset the action spends or sells, or `edit_automation` to change its terms." }, "retryAfterSeconds": { "description": "For a `wait` failure, how long the failing service asked to wait before the same request is repeated, in whole seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "reference": { "description": "Correlation for diagnosis: the request id, or the workflow id of background work. Never a cause.", "type": "string", "maxLength": 128 } }, "required": [ "code", "message" ], "description": "Why the call failed." } }, "required": [ "status", "error" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "pending_input", "description": "The call is paused for a human questionnaire response." }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The questionnaire the user needs to answer." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire expires if it remains unanswered." } }, "required": [ "status", "questionId", "expiresAt" ] } ], "description": "The call's outcome: completed, denied, parked for approval or input, or failed." } }, "required": [ "name", "outcome" ] } }, "required": [ "role", "text" ], "description": "The `agent.entry` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "One durable message in the conversation: the user's message, the assistant's completed reply, or a tool's display text once it resolves. Streaming assistant text arrives first as `agent.text_delta` and lands here only when the turn completes." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "agent.text_delta", "description": "Identifies this as an `agent.text_delta` event." }, "payload": { "type": "object", "properties": { "text": { "type": "string", "description": "The chunk of assistant reply text this delta adds." } }, "required": [ "text" ], "description": "The `agent.text_delta` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A chunk of the assistant's reply while it is still generating. Delivered live only — never written to the durable journal or replayed on reconnect — and superseded by the complete text in the `agent.entry` that follows." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "tool.call", "description": "Identifies this as a `tool.call` event." }, "payload": { "type": "object", "properties": { "callId": { "description": "This call's id, so later events (`approval.opened`, `tool.result`) can be matched to it.", "type": "string" }, "tool": { "type": "string", "description": "The tool's public name." }, "input": { "description": "The call's arguments, scrubbed for public display." }, "batch": { "description": "The calls the agent asked for together in one step. They arrive together in `index` order, and the agent reads every result before its next step, so you can draw them as one group. A call asked for alone has `size` 1. Absent on calls made before this field existed.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 63, "description": "This call's place among them, from 0." }, "size": { "type": "integer", "minimum": 1, "maximum": 64, "description": "How many calls the agent asked for together, this one included." } }, "required": [ "index", "size" ] }, "origin": { "description": "Written by the retired standalone CLI door; kept so its journals still parse.", "type": "string", "const": "cli" } }, "required": [ "tool", "input" ], "description": "The `tool.call` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The assistant asked to call a tool. Emitted once the call is committed to the conversation, before it runs; `approval.opened` follows if a human must decide first, otherwise the call proceeds straight to `tool.result`." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "tool.result", "description": "Identifies this as a `tool.result` event." }, "payload": { "type": "object", "properties": { "callId": { "description": "This call's id, matching the `tool.call` it resolves.", "type": "string" }, "callSeq": { "description": "With `origin`, the retired CLI door's way of pairing a result to its call; historical only.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tool": { "type": "string", "description": "The tool's public name." }, "outcome": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "completed", "description": "The tool ran and returned a result." }, "result": { "description": "The tool's own result value." }, "financialFailures": { "description": "Bounded financial failure display evidence. The tool result and spending authority are unchanged.", "type": "object", "properties": { "nodeFailures": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15 }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ] }, "category": { "type": "string", "enum": [ "price_limit", "insufficient_funds", "unavailable", "integrity", "dependency", "expired", "authority", "conflict", "stopped", "request_blocked", "unknown" ] }, "diagnostic": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "quote_floor", "quote_ceiling" ] }, "classification": { "type": "string", "const": "terms" }, "expectedAtomic": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "observedAtomic": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "inputTokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "outputTokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." } }, "required": [ "rule", "classification", "expectedAtomic", "observedAtomic", "inputTokenId", "outputTokenId" ] } }, "required": [ "index", "reason", "category" ] } }, "preflightFailure": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ] }, "index": { "type": "integer", "minimum": 0, "maximum": 15 }, "diagnostic": { "type": "object", "properties": { "rule": { "type": "string", "enum": [ "quote_floor", "quote_ceiling" ] }, "classification": { "type": "string", "const": "terms" }, "expectedAtomic": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "observedAtomic": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "inputTokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "outputTokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." } }, "required": [ "rule", "classification", "expectedAtomic", "observedAtomic", "inputTokenId", "outputTokenId" ] } }, "required": [ "reason" ] }, "recoverable": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15 }, "kind": { "type": "string", "enum": [ "unclaimed", "refunded", "not_executed" ] } }, "required": [ "index", "kind" ] } }, "recovery": { "description": "Root operations omit this. A recovery child carries a proved original-action map, or null when no safe map is available; null disables recovery controls.", "anyOf": [ { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "originalIndices": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$" } }, "required": [ "operationId", "originalIndices", "maxValueLossBps" ] }, { "type": "null" } ] } } }, "providerRef": { "description": "The upstream provider's own reference, when it returned one.", "type": "string" } }, "required": [ "status", "result" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "denied", "description": "The call was refused before it ran." }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "denied", "egress_denied", "invalid_input", "execution_failed" ], "description": "Why the tool call did not produce a result: `denied` by policy or the user, `egress_denied` for a network destination the tool cannot reach, `invalid_input` for arguments the tool rejected, or `execution_failed` for a fault while it ran." }, "message": { "type": "string", "description": "A human-readable explanation of the failure." }, "hint": { "description": "A suggestion for what to try instead, when there is one.", "type": "string" }, "recovery": { "type": "string", "enum": [ "wait", "owner", "none" ], "description": "Who can fix the failure: `wait` when the same request may succeed later without anyone acting and nothing was signed or sent, `owner` when it fails the same way until the owner acts (the remedy says how), or `none` when this attempt cannot succeed and neither waiting nor the owner changes that, though a later run may. A failure that names no class is `none`." }, "remedy": { "type": "string", "enum": [ "add_funds", "edit_automation" ], "description": "What the owner does about an `owner` failure: `add_funds` of the asset the action spends or sells, or `edit_automation` to change its terms." }, "retryAfterSeconds": { "description": "For a `wait` failure, how long the failing service asked to wait before the same request is repeated, in whole seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "reference": { "description": "Correlation for diagnosis: the request id, or the workflow id of background work. Never a cause.", "type": "string", "maxLength": 128 } }, "required": [ "code", "message" ], "description": "Why the call was denied." } }, "required": [ "status", "error" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "pending_approval", "description": "The call is parked, waiting on a human decision." }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "summary": { "type": "string", "description": "A short human-readable summary of what approving this would do." } }, "required": [ "status", "approvalId", "summary" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "failed", "description": "The call ran but did not complete successfully." }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "denied", "egress_denied", "invalid_input", "execution_failed" ], "description": "Why the tool call did not produce a result: `denied` by policy or the user, `egress_denied` for a network destination the tool cannot reach, `invalid_input` for arguments the tool rejected, or `execution_failed` for a fault while it ran." }, "message": { "type": "string", "description": "A human-readable explanation of the failure." }, "hint": { "description": "A suggestion for what to try instead, when there is one.", "type": "string" }, "recovery": { "type": "string", "enum": [ "wait", "owner", "none" ], "description": "Who can fix the failure: `wait` when the same request may succeed later without anyone acting and nothing was signed or sent, `owner` when it fails the same way until the owner acts (the remedy says how), or `none` when this attempt cannot succeed and neither waiting nor the owner changes that, though a later run may. A failure that names no class is `none`." }, "remedy": { "type": "string", "enum": [ "add_funds", "edit_automation" ], "description": "What the owner does about an `owner` failure: `add_funds` of the asset the action spends or sells, or `edit_automation` to change its terms." }, "retryAfterSeconds": { "description": "For a `wait` failure, how long the failing service asked to wait before the same request is repeated, in whole seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "reference": { "description": "Correlation for diagnosis: the request id, or the workflow id of background work. Never a cause.", "type": "string", "maxLength": 128 } }, "required": [ "code", "message" ], "description": "Why the call failed." } }, "required": [ "status", "error" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "pending_input", "description": "The call is paused for a human questionnaire response." }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The questionnaire the user needs to answer." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire expires if it remains unanswered." } }, "required": [ "status", "questionId", "expiresAt" ] } ], "description": "The call's outcome: completed, denied, parked for approval or input, or failed." }, "origin": { "description": "Written by the retired standalone CLI door; kept so its journals still parse.", "type": "string", "const": "cli" } }, "required": [ "tool", "outcome" ], "description": "The `tool.result` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "One tool call resolved: `outcome` says what happened (completed, denied, parked for approval, or failed). Immediately followed by an `agent.entry` (role `tool`) carrying that outcome's own display text." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "approval.opened", "description": "Identifies this as an `approval.opened` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "callId": { "description": "The tool call this approval parks; absent for direct operations without a model call.", "type": "string" }, "tool": { "type": "string", "description": "The tool name awaiting approval." }, "input": { "description": "The call's arguments, as shown on the approval card." }, "summary": { "type": "string", "description": "A short human-readable summary of what approving this would do." }, "contract": { "description": "Effective terms rendered before approval; absent for tools without authorization contracts.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, "executionRestriction": { "description": "Set when this approval disallows automatic signing; fixed when the approval opened, never inferred from the current UI mode.", "type": "string", "const": "signing_disabled" }, "expiresAt": { "description": "When the parked decision lapses; optional so journal entries written before it still parse.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "approvalId", "tool", "input", "summary" ], "description": "The `approval.opened` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A tool call is parked, waiting on a human decision. Carries the terms the approval card renders: the call's input, a summary, and the authorization contract in effect, if any. `approval.decided` or `approval.expired` closes it." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "approval.decided", "description": "Identifies this as an `approval.decided` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "approve": { "type": "boolean", "description": "True when the user approved; false when denied." }, "reason": { "description": "The user's reason, mainly given with a denial.", "type": "string" }, "attestation": { "description": "The partner-side confirmation cited for the decision; never verified by fin.", "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The partner's own reference for its confirmation." } }, "required": [ "reference" ] }, "decidedBy": { "description": "Which integration released it; absent on journals written before v1, null for the deployment's own app.", "type": "object", "properties": { "partnerKeyId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The partner key that released this decision; null for the deployment's own app." } }, "required": [ "partnerKeyId" ] } }, "required": [ "approvalId", "approve" ], "description": "The `approval.decided` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The user, or a partner integration, approved or denied a parked approval. `approve` says which way; a denial may carry `reason`. Consuming the decision to execute the tool follows as `approval.consumed`, but only when the decision was an approval — a denial never reaches consumption." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "question.opened", "description": "Identifies this as a `question.opened` event." }, "payload": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The questionnaire's unique id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation containing this questionnaire." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run waiting for this questionnaire." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call that opened this questionnaire." }, "questions": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The stable id used to match this question with its answer." }, "label": { "description": "Optional short title for this question.", "type": "string", "minLength": 1, "maxLength": 128 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The question text shown to the user." }, "options": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The stable value returned when this option is selected." }, "label": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The text shown to the user for this option." }, "description": { "description": "Optional explanation shown with this option.", "type": "string", "maxLength": 512 }, "recommended": { "description": "Whether this is the option the agent recommends: at most one per question, with why in its description.", "type": "boolean" }, "picture": { "description": "A small drawing an app may show over this choice: `schedule` for buying on a regular schedule, `dip` for buying only after a fall, `once` for one buy now. Absent when none fits; an app that draws none shows the choice without it.", "type": "string", "enum": [ "schedule", "dip", "once" ] } }, "required": [ "value", "label" ], "description": "One choice presented for a question." }, "description": "The choices shown for this question." }, "multiple": { "description": "Whether the user may select more than one choice.", "type": "boolean" }, "amount": { "type": "object", "properties": { "min": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The smallest amount the slider offers, as a decimal string." }, "max": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The largest amount the slider offers, as a decimal string." }, "step": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "How far one slider step moves, as a decimal string." }, "unit": { "type": "string", "minLength": 1, "maxLength": 16, "description": "What the amount counts: \"usd\" for dollars, or a token symbol such as \"USDC\"." } }, "required": [ "min", "max", "step", "unit" ], "description": "Asks for one amount on a slider. The options are its presets, each value a decimal string within min and max; an amount between them is answered as customText." } }, "required": [ "id", "prompt", "options" ], "description": "One question and its available choices." }, "description": "The questions and choices shown to the user." }, "status": { "type": "string", "enum": [ "pending", "answered", "skipped", "expired", "cancelled" ], "description": "The current questionnaire status." }, "answer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "answered", "description": "The questionnaire was answered." }, "answers": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The id of the question this answer corresponds to." }, "values": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Selected option values; empty when customText is supplied." }, "customText": { "description": "Optional user-supplied text in place of selected options.", "type": "string", "maxLength": 2048 } }, "required": [ "id", "values" ], "description": "The user's answer to one question." }, "description": "The selected options or custom text for each question the user answered. A question they skipped has no answer." } }, "required": [ "status", "answers" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "skipped", "description": "The questionnaire was skipped." } }, "required": [ "status" ] } ], "description": "The result of answering or skipping a questionnaire." }, { "type": "null" } ], "description": "The accepted answers or skip result, or null when none was accepted." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire was created." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire expires if unanswered." }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the questionnaire was answered, skipped, expired, or cancelled; null while pending." } }, "required": [ "id", "conversationId", "runId", "callId", "questions", "status", "answer", "createdAt", "expiresAt", "resolvedAt" ], "description": "The `question.opened` event's full resource." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A questionnaire is waiting for the user. Its full content is durable and replayable." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "question.answered", "description": "Identifies this as a `question.answered` event." }, "payload": { "type": "object", "properties": { "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The questionnaire that was resolved." }, "answer": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "answered", "description": "The questionnaire was answered." }, "answers": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The id of the question this answer corresponds to." }, "values": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Selected option values; empty when customText is supplied." }, "customText": { "description": "Optional user-supplied text in place of selected options.", "type": "string", "maxLength": 2048 } }, "required": [ "id", "values" ], "description": "The user's answer to one question." }, "description": "The selected options or custom text for each question the user answered. A question they skipped has no answer." } }, "required": [ "status", "answers" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "skipped", "description": "The questionnaire was skipped." } }, "required": [ "status" ] } ], "description": "The user's answers or decision to skip." }, "resolvedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire was answered or skipped." } }, "required": [ "questionId", "answer", "resolvedAt" ], "description": "The `question.answered` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The user answered or skipped a questionnaire; its accepted result is durable." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "question.closed", "description": "Identifies this as a `question.closed` event." }, "payload": { "type": "object", "properties": { "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The questionnaire that was closed." }, "status": { "type": "string", "enum": [ "expired", "cancelled" ], "description": "Why the questionnaire closed without an answer." }, "resolvedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire closed." } }, "required": [ "questionId", "status", "resolvedAt" ], "description": "The `question.closed` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A pending questionnaire expired or was cancelled." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "approval.consumed", "description": "Identifies this as an `approval.consumed` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." } }, "required": [ "approvalId" ], "description": "The `approval.consumed` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The approval was spent to authorize its tool call, immediately before that call runs. This is when the call is authorized, not when it finishes: the call can still fail after this event lands, and nothing here rolls it back. Marks the approval used; it cannot authorize a second execution." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "approval.expired", "description": "Identifies this as an `approval.expired` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "reason": { "type": "string", "description": "Why the approval expired: the deadline passed, or its run stopped first." } }, "required": [ "approvalId", "reason" ], "description": "The `approval.expired` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A parked approval lapsed before anyone decided: its deadline passed, or the run it belongs to stopped while it was still pending." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "automation.fired", "description": "Identifies this as an `automation.fired` event." }, "payload": { "type": "object", "properties": { "automationId": { "type": "string", "description": "The automation that fired this run." }, "name": { "type": "string", "description": "The automation's name at the time it fired." } }, "required": [ "automationId", "name" ], "description": "The `automation.fired` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "An automation triggered this conversation's run. Emitted once, immediately before the `run.started` it precedes, naming the automation and its name at fire time." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "intents.settlement", "description": "Identifies this as an `intents.settlement` event." }, "payload": { "oneOf": [ { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current receipts use `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "settled", "description": "The leg settled: its output asset moved as planned." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What the leg produced." } }, "required": [ "approvalId", "legId", "index", "state", "output" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current receipts use `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "refunded", "description": "The leg did not settle and its input asset was returned." }, "refund": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What was returned." } }, "required": [ "approvalId", "legId", "index", "state", "refund" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current receipts use `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "not_executed", "description": "The leg did not settle. Most reasons mean it never reached the provider; `rejected` means it did and was refused there — see `reason`." }, "reason": { "description": "Why nothing executed: `signing_disabled` when automatic signing was off, `signing_failed` when signing itself failed, `rejected` when the provider refused the submission outright (it did reach the provider), `expired` when the leg's own signing/deposit window elapsed before a terminal fact arrived, or `failed` otherwise. Optional so receipts written before the reason was carried still parse.", "type": "string", "enum": [ "signing_disabled", "signing_failed", "rejected", "expired", "failed" ] }, "unsignedBy": { "description": "Present with `signing_failed` on an Agent API wallet's leg when the NEAR Intents Agent API, the wallet's signer, released no signature for it: it refused the request, or its own history proves it released none. Nothing moved.", "type": "string", "const": "agent_api" } }, "required": [ "approvalId", "legId", "index", "state" ] } ], "description": "The `intents.settlement` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A later, independently verified financial fact about one leg of an authorized swap — settled, refunded, or never executed — never inferred from the model's own tool result. Appended whenever the provider confirms the outcome, independent of the run that requested it; `legId` and `operationId` join it back to its financial request, progress and authorizing approval. Archived receipts retain their original `occurrenceId`." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "intents.progress", "description": "Identifies this as an `intents.progress` event." }, "payload": { "oneOf": [ { "type": "object", "properties": { "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current progress uses `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grant's approval id: the chat approval for a one-shot, the creation approval for an automation." }, "kind": { "type": "string", "const": "planning", "description": "Authorized; reading balances and prices to freeze the plan." } }, "required": [ "approvalId", "kind" ] }, { "type": "object", "properties": { "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current progress uses `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grant's approval id: the chat approval for a one-shot, the creation approval for an automation." }, "kind": { "type": "string", "const": "planned", "description": "The frozen plan: every swap, with the amount on the side the plan fixed." }, "legs": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "The input asset and, when the plan fixed this side, the exact amount it spends." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "The output asset and, when the plan fixed this side, the exact amount it receives." }, "minimumOutputRaw": { "description": "The floor an exact-input swap's output must clear; present only when the input side is fixed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "maximumInputRaw": { "description": "The ceiling an exact-output swap's input may spend; present only when the output side is fixed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "index", "input", "output" ] }, "description": "Every swap in the frozen plan, indexed from zero." } }, "required": [ "approvalId", "kind", "legs" ] }, { "type": "object", "properties": { "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current progress uses `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grant's approval id: the chat approval for a one-shot, the creation approval for an automation." }, "kind": { "type": "string", "const": "stage", "description": "One swap moved; `legId` joins it to its receipt once the swap is claimed." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "Which leg, by position, this update is about." }, "stage": { "type": "string", "enum": [ "checking", "retrying", "quoting", "signed", "confirming", "unresolved" ], "description": "What the executor is doing right now, between approval and a receipt: `checking` while it checks the complete frozen request before dispatch; `retrying` while a bounded preparation attempt waits to retry; `quoting` while it fetches and validates the provider quote, then claims and signs; `signed` once the signature is persisted, about to submit; `confirming` once submitted (or recovered), waiting for the provider's terminal fact; `unresolved` when the run's settle budget ended before a terminal fact and the sweep continues." }, "legId": { "description": "Joins this stage to its settlement receipt once the swap is claimed; absent before then.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "approvalId", "kind", "index", "stage" ] } ], "description": "The `intents.progress` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "Best-effort, display-only progress for an authorized swap, between approval and its settlement receipt: freezing the plan (`planning`), the frozen legs (`planned`), then each leg's own stage (`stage`). Never gates execution and may arrive out of order or not at all; an `intents.settlement` receipt always takes precedence, and a terminal outcome is never reported here." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "perps.reconciled", "description": "Identifies this as a `perps.reconciled` event." }, "payload": { "oneOf": [ { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that authorized the call." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The durable financial request this answer belongs to." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call whose own result this answer supersedes, as `tool.result` names it." }, "tool": { "type": "string", "enum": [ "perps_order_place", "perps_order_cancel", "perps_margin_update" ], "description": "The order placement, cancellation or margin change Hyperliquid has now answered." }, "result": { "description": "Hyperliquid's final answer, in the shape the tool itself returns: `placed`, `rejected`, `cancelled` or `applied`.", "$ref": "#/components/schemas/PerpsOrderOutcome" } }, "required": [ "approvalId", "operationId", "callId", "tool", "result" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that authorized the call." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The durable financial request this answer belongs to." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call whose own result this answer supersedes, as `tool.result` names it." }, "tool": { "type": "string", "const": "perps_withdraw", "description": "The withdrawal whose settlement the provider has now confirmed." }, "result": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ], "description": "The confirmed ending, in the shape the tool itself returns: `settled` or `refunded`." } }, "required": [ "approvalId", "operationId", "callId", "tool", "result" ] } ], "description": "The `perps.reconciled` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A later, independently verified answer to an approved perps order, cancellation or withdrawal whose own `tool.result` was left unconfirmed — never inferred from the model's own tool result. Appended once, by recovery, in the same commit that records the request's final outcome, independent of the run that made the call; `callId` joins it to that call's `tool.result`, `approvalId` to its approval, and `operationId` to its financial request. `result` has the shape the tool itself returns; show it in place of the call's earlier unconfirmed result." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "prediction.funding", "description": "Identifies this as a `prediction.funding` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that authorized the call." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The durable financial request this answer belongs to." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call whose own result this answer supersedes, as `tool.result` names it." }, "tool": { "type": "string", "const": "prediction_fund", "description": "The funding tool whose call this updates." }, "result": { "description": "The funding's current stages, in the shape the tool itself returns.", "$ref": "#/components/schemas/PredictionFundSubmitted" } }, "required": [ "approvalId", "operationId", "callId", "tool", "result" ], "description": "The `prediction.funding` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "Recovery's latest view of an approved `prediction_fund` call, appended whenever it changes, independent of the run that made the call: the first leg's verified 1Click outcome (native Base USDC delivered to Polymarket's bridge, refunded, or not executed) and every transaction the bridge reports at the pinned deposit address, each `COMPLETED` one checked against its canonical Polygon receipt. Delivery to the bridge is not pUSD funding, a bridge `FAILED` is not a refund, and attribution of any bridge transaction to this funding stays unknown. `callId` joins it to that call's `tool.result`; show the latest in place of it." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "prediction.withdrawal", "description": "Identifies this as a `prediction.withdrawal` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that authorized the call." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The durable financial request this answer belongs to." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call whose own result this answer supersedes, as `tool.result` names it." }, "tool": { "type": "string", "const": "prediction_withdraw" }, "result": { "$ref": "#/components/schemas/PredictionWithdrawSubmitted" } }, "required": [ "approvalId", "operationId", "callId", "tool", "result" ], "description": "The attempted withdrawal's outgoing receipt, bridge observation and unique linked deposit arrival." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "Recovery's latest view of an attempted owner-approved pUSD withdrawal, independent of the run: its outgoing Polygon transfer receipt, what the bridge reports, and arrival at the unique linked 1Click deposit address. Only that deposit's own receipt establishes a credit or refund into the agent's confidential Intents wallet. A bridge status alone is not a receipt. Replace the original tool result by callId; recovery never signs or resends." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "composite.progress", "description": "Identifies this as a `composite.progress` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The `composite_execute` call." }, "revision": { "type": "integer", "minimum": 1, "maximum": 1024, "description": "Snapshot order: ignore an older snapshot for the same call." }, "pieces": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 5 }, "tool": { "type": "string", "enum": [ "intents_execute", "perps_fund", "perps_order_place", "prediction_fund", "prediction_order_place", "perps_withdraw", "prediction_withdraw" ] }, "operationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "todo", "live", "done", "bad", "skip" ], "description": "`todo` waiting, `live` running, `done` executed, `bad` failed, `skip` never started because a piece it depends on did not succeed or the basket ended." }, "reason": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "index", "tool", "operationId", "state" ] } } }, "required": [ "approvalId", "callId", "revision", "pieces" ], "description": "Display-only basket piece states." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "Best-effort display snapshot of an approved basket's pieces (`composite_execute`), appended after a piece changes state: each piece `todo`, `live`, `done`, `bad` or `skip`. Revision orders snapshots for the same call; ignore an older one. The call's own `tool.result` is the authoritative outcome of every piece, and each piece's own venue events keep their meaning; progress grants no execution permission." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "solana.progress", "description": "Identifies this as a `solana.progress` event." }, "payload": { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The original tool call, including a standing occurrence without its own approval card." }, "revision": { "type": "integer", "minimum": 1, "maximum": 1024, "description": "Persisted lifecycle stage number. Ignore an older snapshot for the same operation." }, "phase": { "type": "string", "enum": [ "funding", "swap", "sweep" ] }, "state": { "type": "string", "enum": [ "preparing", "prepared", "submitting", "pending", "delivering", "confirmed", "uncertain", "refunded", "failed", "not_executed" ] }, "transactionIndex": { "description": "The stored native transaction attempt, never a funding plan leg index.", "type": "integer", "minimum": 0, "maximum": 5 }, "sale": { "description": "On a multi-coin sale's swap, which coin it sells: its zero-based place in the sale's `sells`. A multi-coin sale's progress names this in place of `transactionIndex`, and nothing on its one transfer back; absent on every other operation.", "type": "integer", "minimum": 0, "maximum": 5 }, "paid": { "description": "What a sale sold, once its swap landed: the amount its result reports as `paid`. Absent before then, and for other operations.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] } }, "required": [ "operationId", "approvalId", "callId", "revision", "phase", "state" ], "description": "Display-only committed Solana stage, never a final operation result." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "Best-effort display snapshot derived from committed Solana funding, swap or sweep facts. Revision orders snapshots; repeated unchanged observations are omitted. A confirmed funding phase is only delivered SOL, and a confirmed swap phase does not establish sweep settlement. Final tool outcomes and solana.reconciled remain authoritative; progress grants no execution permission." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "solana.reconciled", "description": "Identifies this as a `solana.reconciled` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that authorized the call." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The durable financial request this answer belongs to." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call whose own result this answer supersedes, as `tool.result` names it." }, "tool": { "type": "string", "enum": [ "solana_buy", "solana_sell", "solana_sell_many", "solana_withdraw" ], "description": "The Solana buy, sell, multi-coin sale or withdrawal whose outcome is now known." }, "result": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ], "description": "The confirmed ending, in the shape the tool itself returns, with its `solana` detail." } }, "required": [ "approvalId", "operationId", "callId", "tool", "result" ], "description": "The `solana.reconciled` event's own fields." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "A later, independently verified answer to an approved Solana buy, sell or withdrawal whose own `tool.result` was left unconfirmed — never inferred from the model's own tool result. Appended once, by recovery, in the same commit that records the request's final outcome, independent of the run that made the call; `callId` joins it to that call's `tool.result`, `approvalId` to its approval, and `operationId` to its financial request. `result` has the shape the tool itself returns, with its `solana` detail; show it in place of the call's earlier unconfirmed result." }, { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The event's position in the conversation's journal; strictly increasing." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event was appended to the journal." }, "requestId": { "description": "The request that produced this event, when one did; null for scheduler and recovery writes.", "type": [ "string", "null" ] }, "type": { "type": "string", "const": "prediction.order", "description": "Identifies this as a `prediction.order` event." }, "payload": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that authorized the call." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The durable financial request this answer belongs to." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call whose own result this answer supersedes, as `tool.result` names it." }, "tool": { "type": "string", "const": "prediction_order_place" }, "result": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "submitted" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "observation": { "type": "object", "properties": { "orderId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "status": { "type": "string", "enum": [ "live", "partially_filled", "matched", "filled", "cancelled", "expired", "rejected", "uncertain" ] }, "originalSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "matchedSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "remainingSizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tradeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED" ] }, "sizeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "tradeId", "status", "sizeRaw" ] } }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "settledCollateralRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "settledFeeRaw": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "cancelRequested": { "type": "boolean" }, "polymarketError": { "description": "What Polymarket answered when the order was sent, when it answered with an error: kept with the order for good. Absent when Polymarket gave no reason.", "type": "object", "properties": { "httpStatus": { "description": "The HTTP status Polymarket answered with, when it answered with an error status.", "type": "integer", "minimum": 100, "maximum": 599 }, "message": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Polymarket's own words, exactly as it answered, cut to their first 300 characters." } }, "required": [ "message" ] } }, "required": [ "orderId", "status", "originalSizeRaw", "matchedSizeRaw", "remainingSizeRaw", "trades", "observedAtMs" ] } }, "required": [ "status", "operationId", "order", "observation" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "blocked" }, "reason": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "status", "reason" ] } ] } }, "required": [ "approvalId", "operationId", "callId", "tool", "result" ], "description": "The original Polymarket order's latest observed state, not a new placement." } }, "required": [ "seq", "conversationId", "createdAt", "requestId", "type", "payload" ], "description": "The latest observation of a Polymarket order. Replace the original placement call's result, joined by `callId`, with `result`. A match is not settlement; cancellation stops only the unmatched part and does not reverse earlier fills. Observations can arrive after the run ends." } ], "description": "One journal entry: the event type and its payload, in the order it happened." }, "LimitOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "limit_order", "description": "Which contract template this is." }, "order": { "type": "object", "properties": { "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order sells: token id and decimals." } }, "required": [ "pinned" ], "description": "The input (base) asset this order sells." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order buys: token id and decimals." } }, "required": [ "pinned" ], "description": "The output (quote) asset this order buys." }, "quantity": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount to sell, in the input asset's smallest unit. 1 NEAR with verified decimals 24 is \"1000000000000000000000000\". Scale decimal digits with the verified decimals and reject excess fractional digits; no floating-point arithmetic or bash." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The minimum price the fill must reach, as output-asset units per ONE input unit, written as a plain human decimal: \"5\" means at least 5 output tokens per 1 input token. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order may rest before it expires, in whole hours. Use the user's duration within this wallet's maximum, or the wallet's default from the latest request's host context when none is given. The schema permits up to 720 hours (30 days); a wallet may have a lower maximum. Never shorten a requested duration to fit." } }, "required": [ "input", "output", "quantity", "limitPrice", "expiresInHours" ], "description": "The exact approved placement request." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest instant the order may be created and funded under this consent." } }, "required": [ "type", "order", "validUntil" ], "description": "Owner-signed authority for one resting limit order: the exact approved placement, created and funded once by the policy worker before the approval expires." }, "PerpsTransferContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_transfer", "description": "Which authorization contract this is." }, "direction": { "type": "string", "enum": [ "fund", "withdraw" ], "description": "Fund the own perps account from the agent wallet, or withdraw back to the same agent wallet." }, "transfer": { "description": "The exact approved amount and all-in loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PerpsTransferInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "direction", "transfer", "validUntil" ], "description": "One approved perps transfer in exactly the named direction." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "PerpsOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_order", "description": "Which authorization contract this is." }, "order": { "description": "The exact approved order.", "$ref": "#/components/schemas/PerpsOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "order", "validUntil" ], "description": "One approved Hyperliquid order, signed once exactly as approved." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsCancelContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_cancel", "description": "Which authorization contract this is." }, "cancel": { "description": "The exact order approved for cancelling.", "$ref": "#/components/schemas/PerpsCancelInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "cancel", "validUntil" ], "description": "One approved cancellation of one resting Hyperliquid order." }, "PerpsCancelInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "oid": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The resting order's id exactly as perps_orders lists it." } }, "required": [ "coin", "asset", "oid" ], "description": "Cancel one resting order on the agent's own account." }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PerpsMarginContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_margin", "description": "Which authorization contract this is." }, "margin": { "description": "The exact approved margin change.", "$ref": "#/components/schemas/PerpsMarginInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "margin", "validUntil" ], "description": "One approved change to one isolated position's margin, signed once exactly as approved." }, "PerpsMarginInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "change": { "type": "string", "enum": [ "add", "remove" ], "description": "`add` moves USDC from the account into the position's isolated margin, lowering its liquidation risk; `remove` takes it back out, raising that risk. A strict isolated market never lets margin be removed while the position is open." }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,8})(\\.[0-9]{0,5}[1-9])?$", "description": "Exact USDC to move, at most six decimal places, such as `25` or `12.5`." } }, "required": [ "coin", "asset", "change", "amount" ], "description": "Add or remove margin on one isolated position on the agent's own account." }, "PredictionFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_fund", "description": "One approved Polymarket funding transfer." }, "transfer": { "description": "The exact approved USDC or USDT debit and the first leg's loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PredictionFundInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "transfer", "validUntil" ], "description": "One exact USDC or USDT debit delivered as native Base USDC to Polymarket's bridge for the agent's own account; the final pUSD amount is not bounded." }, "PredictionFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact debit in six-decimal atomic units: 5 USDC or USDT is \"5000000\", spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it. The host resolves the agent’s own Polymarket Deposit Wallet and its bridge address; never supply an address." }, "maxFirstLegLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum loss, in basis points, of the first leg only: the wallet's USDC, USDT or coin delivered as native Base USDC to Polymarket's bridge, fees and any cross-chain hop included. It does not bound the bridge's conversion to pUSD on Polygon, whose fees and output are variable and estimated. Required; no default." }, "payWith": { "description": "Approved in chat as one call or as a funded order's funding: the coin the first leg pays with instead of a USDC or USDT holding, and the most of it it may spend.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxFirstLegLossBps" ], "description": "Fund the agent's own Polymarket Deposit Wallet: one exact USDC or USDT debit, or that many dollars of a coin, delivered as native Base USDC to Polymarket's bridge, which credits an estimated, not guaranteed, pUSD amount on Polygon later." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "SolanaFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_fund", "description": "Which authorization contract this is." }, "fund": { "description": "The exact approved amount and loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaFundInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "fund", "maxExecutions", "validUntil" ], "description": "An approved move of USDC or USDT, or a coin, into the agent's own Solana account." }, "SolanaFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to move from the agent wallet into the agent's Solana account as SOL, in six-decimal atomic units: 5 USDC is \"5000000\". Spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." }, "payWith": { "description": "Approved in chat as one call: the coin this funding pays with instead of a USDC or USDT holding, and the most of it it may spend. Never SOL.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "Move an exact amount of USDC or USDT, or that many dollars of a coin, from the agent wallet into its own Solana account as SOL." }, "SolanaWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_withdraw", "description": "Which authorization contract this is." }, "withdraw": { "description": "The exact approved amount, what returns and the loss bound.", "$ref": "#/components/schemas/SolanaWithdrawInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "withdraw", "maxExecutions", "validUntil" ], "description": "An approved move of SOL from the agent's own Solana account back to its agent wallet." }, "SolanaWithdrawInput": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Withdraw an exact amount of SOL." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to withdraw, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Withdraw an exact amount of SOL." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_spendable", "description": "Withdraw all the SOL above the reserve the account keeps for rent and network fees." } }, "required": [ "kind" ], "description": "Withdraw all the spendable SOL." } ], "description": "How much SOL to withdraw from the agent's Solana account." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns it to the agent wallet as USDC on NEAR; `sol` returns it to the agent wallet as SOL." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." } }, "required": [ "amount", "receive", "maxValueLossBps" ], "description": "Move SOL from the agent's own Solana account back to its agent wallet." }, "PredictionOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_order" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "order", "validUntil" ] }, "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "PredictionWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_withdraw" }, "withdrawal": { "$ref": "#/components/schemas/PredictionWithdrawInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ] }, "PredictionWithdrawInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact pUSD debit in six-decimal atomic units: 5 pUSD is \"5000000\". Only the agent’s own Deposit Wallet is spent." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "amountRaw", "maxLossBps" ], "description": "Withdraw pUSD through Polymarket’s conversion service as native USDC on Polygon to a unique verified 1Click address crediting only the agent’s own confidential Intents wallet. Funding remains a separate USDC route." }, "CompositeContract": { "type": "object", "properties": { "type": { "type": "string", "const": "composite", "description": "Which authorization contract this is." }, "pieces": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "intents_execute", "perps_fund", "perps_order_place", "prediction_fund", "prediction_order_place", "perps_withdraw", "prediction_withdraw" ], "description": "The tool whose one-shot call this piece is." }, "contract": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, "startBy": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "tool", "contract", "startBy" ] } }, "dependencies": { "type": "array", "items": { "maxItems": 6, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "walletDebit": { "anyOf": [ { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, { "type": "array", "prefixItems": [], "items": false, "maxItems": 0 } ], "description": "The sum of every piece's debit from the agent wallet, per token, in raw units. Empty when the pieces are venue orders paid from money already on their venues, as when finishing a basket, or a cash-out, which closes a position and brings home what that freed." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When every piece that has not started loses its authority." } }, "required": [ "type", "pieces", "dependencies", "walletDebit", "validUntil" ], "description": "One owner signature over several exact one-shot grants and the order they run in." }, "PerpsFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_freed_withdrawal", "description": "Which authorization contract this is." }, "withdrawal": { "description": "The signed maximum and all-in loss bound of the withdrawal home.", "$ref": "#/components/schemas/PerpsFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's exit freed on Hyperliquid, at most the signed maximum. Only ever a piece of a cash-out." }, "PerpsFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic USDC: what the exit before it frees, sized by the host before the approval opens. Never more than the exit freed." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." } }, "required": [ "upToRaw", "maxValueLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the exit before it freed on its own Hyperliquid account, never more than upToRaw." }, "PredictionFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_freed_withdrawal" }, "withdrawal": { "$ref": "#/components/schemas/PredictionFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's sale freed on Polymarket, at most the signed maximum. Only ever a piece of a cash-out." }, "PredictionFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic pUSD: what the sale before it frees, sized by the host before the approval opens. Never more than the sale freed." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "upToRaw", "maxLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the sale before it freed in its own Polymarket Deposit Wallet, never more than upToRaw." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaSellManyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell_many", "description": "Which authorization contract this is." }, "sellMany": { "description": "The exact approved coins, amounts and loss bounds, in order, and where the proceeds go.", "$ref": "#/components/schemas/SolanaSellManyInput" }, "maxExecutions": { "type": "number", "const": 1, "description": "A multi-coin sale is approved once and runs once: always 1." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sellMany", "maxExecutions", "validUntil" ], "description": "An approved multi-coin Solana sale, executed only exactly as approved." }, "SolanaSellManyInput": { "type": "object", "properties": { "sells": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/SolanaSale" }, "description": "The coins to sell, in the order they are sold: 2 to 6, each a different mint, none of them SOL itself." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the summed proceeds of every sale that went through to the agent wallet as USDC on NEAR, in one transfer once the last sale ran; `sol` keeps them as SOL in the agent's Solana account." } }, "required": [ "sells", "receive" ], "description": "Several sells of Solana tokens held in the agent's own Solana account, approved together and run as one: each sale on its own, one after another, then one transfer of what they returned." }, "SolanaSale": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "maxValueLossBps" ], "description": "One coin of a multi-coin sale, sold through the agent's own Solana account." }, "GridContract": { "type": "object", "properties": { "type": { "type": "string", "const": "grid", "description": "Which contract template this is." }, "grid": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "A grid's exact terms: pair, levels, quantity and starting sides." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends: no order is placed, and none rests, after it. At most 720 hours after the approval's own expiry." } }, "required": [ "type", "grid", "validUntil" ], "description": "Owner-signed authority for one grid: the resting cell orders its terms derive, until it ends." }, "PerpsOrderOutcome": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "placed", "rejected", "uncertain", "cancelled", "applied", "not_executed" ], "description": "`placed` Hyperliquid accepted the order (see each placement), `rejected` it accepted none (or refused the margin change), `uncertain` the answer was lost and the host reconciles what is still unknown by client order id (a trailing stop with no answer only when one order matches its terms; a margin change from the account's own transaction list), `cancelled` the cancellation took effect, `applied` the margin change took effect, `not_executed` nothing was signed." }, "placements": { "maxItems": 4, "type": "array", "items": { "$ref": "#/components/schemas/PerpsPlacementOutcome" }, "description": "Each placement's own answer, in the order's order: entry, take-profit, stop-loss, then trailing stop." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why nothing was placed or the cancellation did not take effect, in Hyperliquid's or the host's words; null otherwise." } }, "required": [ "status", "placements", "reason" ], "description": "The result of one approved perps order, cancellation or margin change." }, "PerpsPlacementOutcome": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "entry", "take_profit", "stop_loss", "trailing_stop" ], "description": "Which part of the order: `entry`, `take_profit`, `stop_loss` or `trailing_stop`." }, "cloid": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-f]{32}$" }, { "type": "null" } ], "description": "The client order id it is reconciled by; null for a trailing stop, which Hyperliquid gives none and the host matches by its terms instead." }, "state": { "type": "string", "enum": [ "filled", "resting", "triggered_pending", "triggered", "cancelled", "rejected", "unknown" ], "description": "`filled` executed (possibly partly; see `filledSize`), `resting` waits on the book, `triggered_pending` is an exit waiting for its trigger, `triggered` is an exit whose trigger fired and became a market order (its fill is in the account's fills, not here), `rejected` never placed, `unknown` not yet known: never resubmit it." }, "oid": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Hyperliquid's order id once it named one; null for a trigger it answered without one, or an answer not yet known." }, "filledSize": { "description": "How much filled, in the coin, as Hyperliquid wrote it; null when nothing filled or it did not say.", "type": [ "string", "null" ] }, "averagePrice": { "description": "The average fill price, as Hyperliquid wrote it; null when it did not say.", "type": [ "string", "null" ] }, "error": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Hyperliquid's own refusal text for this placement; null otherwise." } }, "required": [ "role", "cloid", "state", "oid", "filledSize", "averagePrice", "error" ], "description": "What one placement of an order came to on Hyperliquid." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "PredictionFundSubmitted": { "type": "object", "properties": { "status": { "type": "string", "const": "submitted", "description": "The exact USDC debit was attempted." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "firstLeg": { "$ref": "#/components/schemas/PredictionFirstLeg" }, "bridge": { "type": "object", "properties": { "depositWallet": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "The agent's own Polymarket Deposit Wallet." }, "bridgeAddress": { "type": "string", "pattern": "^0x[0-9a-f]{40}$", "description": "The bridge deposit address the first leg paid, pinned before signing." }, "minDepositRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The bridge's minimum for native Base USDC when the address was pinned." }, "observation": { "$ref": "#/components/schemas/PredictionBridgeObservation" } }, "required": [ "depositWallet", "bridgeAddress", "minDepositRaw", "observation" ] }, "attribution": { "$ref": "#/components/schemas/PredictionFundAttribution" }, "balance": { "description": "The Deposit Wallet's live pUSD balance, read for the call's own answer and each `prediction.funding` change. Absent only from an answer rebuilt from the record without a live read, or recorded before balances were reported.", "$ref": "#/components/schemas/PredictionDepositWalletBalance" } }, "required": [ "status", "operationId", "firstLeg", "bridge", "attribution" ] }, "PredictionFirstLeg": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "pending" } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "delivered_to_bridge" }, "deliveredRaw": { "description": "Native Base USDC 1Click reported delivered to the bridge address; absent when its settlement stated no figure.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "refunded" }, "refundedRaw": { "description": "The USDC 1Click reported refunded to the agent wallet, in the asset the first leg spent; absent when its refund stated no figure.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "not_executed" } }, "required": [ "state" ] } ], "description": "The first leg's verified 1Click outcome, or `pending` while it has none." }, "PredictionBridgeObservation": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "not_observed", "description": "Nothing was delivered to the bridge yet, so its status was not read." } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "unavailable", "description": "The bridge's status could not be read." }, "attemptedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "state", "attemptedAtMs" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "observed" }, "observedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "complete": { "type": "boolean", "description": "Whether every page was read; false when the walk stopped at its bound." }, "transactions": { "maxItems": 500, "type": "array", "items": { "$ref": "#/components/schemas/PredictionBridgeTransaction" }, "description": "Every transaction the bridge reports at the address, newest first." } }, "required": [ "state", "observedAtMs", "complete", "transactions" ] } ] }, "PredictionBridgeTransaction": { "type": "object", "properties": { "status": { "type": "string", "pattern": "^[A-Z][A-Z_]{0,63}$", "description": "The bridge's status, verbatim: documented `DEPOSIT_DETECTED`, `PROCESSING`, `ORIGIN_TX_CONFIRMED`, `SUBMITTED`, `COMPLETED`, `FAILED`. `FAILED` is not a refund." }, "fromChainId": { "type": "string", "minLength": 1, "maxLength": 32 }, "fromTokenAddress": { "type": "string", "minLength": 1, "maxLength": 128 }, "fromAmountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "toChainId": { "type": "string", "minLength": 1, "maxLength": 32 }, "toTokenAddress": { "type": "string", "minLength": 1, "maxLength": 128 }, "createdTimeMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "txHash": { "description": "The bridge's own hash for the row, reported once `COMPLETED`. It names no Polygon transaction: the onramp row's is an ERC-4337 user operation's, and the Base row's is no chain's transaction. Never evidence of arrival.", "type": "string", "minLength": 1, "maxLength": 128 }, "routeMatches": { "type": "boolean", "description": "Whether the row has the pinned route's shape. Shape alone never links a bridge row to a particular funding or withdrawal." }, "credit": { "description": "Recorded only by releases before 2026-11-15, which read the row's hash as a Polygon transaction; never written now. A funding's arrival is its `attribution`, a withdrawal's the linked deposit receipt.", "$ref": "#/components/schemas/PredictionBridgeCredit" } }, "required": [ "status", "fromChainId", "fromTokenAddress", "fromAmountRaw", "toChainId", "toTokenAddress", "routeMatches" ] }, "PredictionBridgeCredit": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "verified" }, "blockNumber": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The finalized canonical block, as a decimal." }, "blockHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "logIndex": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "creditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The pUSD this receipt's one incoming log credited to the Deposit Wallet, with no pUSD leaving it in the same transaction; six-decimal atomic units." } }, "required": [ "state", "blockNumber", "blockHash", "logIndex", "creditRaw" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "not_credited" }, "reason": { "type": "string", "enum": [ "reverted", "no_credit_log", "multiple_credit_logs", "outgoing_in_transaction" ], "description": "`reverted` the transaction failed; `no_credit_log` no pUSD transfer to the Deposit Wallet; `multiple_credit_logs` more than one, so no single credit can be named; `outgoing_in_transaction` pUSD also left the Deposit Wallet in the same transaction, so no net credit is named." } }, "required": [ "state", "reason" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "unconfirmed", "description": "No receipt yet, or its block is not finalized and canonical yet." } }, "required": [ "state" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "unavailable", "description": "Polygon could not be read; nothing is inferred." } }, "required": [ "state" ] } ] }, "PredictionFundAttribution": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "credited", "description": "This funding's pUSD arrived in the Deposit Wallet." }, "creditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The pUSD the one matching receipt credited to the Deposit Wallet; six-decimal atomic units." }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "The Polygon transaction that credited it." } }, "required": [ "state", "creditRaw", "transactionHash" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "unknown" }, "reason": { "type": "string", "enum": [ "not_at_bridge", "delivery_unmeasured", "bridge_not_read", "awaiting_bridge", "credit_not_verified", "ambiguous", "provider_reports_no_source_link" ], "description": "`not_at_bridge` step 1 has not delivered to the bridge; `delivery_unmeasured` 1Click reported no delivered figure or the leg has no signing time, so no conversion can be matched; `bridge_not_read` Polygon could not be read just now, or this answer was rebuilt from the record without reading it; `awaiting_bridge` Polygon shows no conversion of the delivered amount out of the bridge address yet; `credit_not_verified` the one matching conversion's receipt shows no single pUSD credit to the Deposit Wallet; `ambiguous` more than one conversion of the delivered amount, or another of the owner's open fundings at the address, could be this one; `provider_reports_no_source_link` recorded by a release that never attributed." }, "candidates": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Finalized transfers of exactly the delivered amount out of the bridge address on Polygon after the first leg was signed, not credited to another funding." } }, "required": [ "state", "reason", "candidates" ] } ] }, "PredictionDepositWalletBalance": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "observed" }, "pusdRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "pUSD the wallet holds; six-decimal atomic units." }, "readAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "state", "pusdRaw", "readAtMs" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "unavailable", "description": "Polygon could not be read; nothing is inferred." }, "attemptedAtMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "state", "attemptedAtMs" ] } ], "description": "The wallet's whole balance, never this funding's amount." }, "PredictionWithdrawSubmitted": { "type": "object", "properties": { "status": { "type": "string", "const": "submitted" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "transfer": { "$ref": "#/components/schemas/PredictionWithdrawTransfer" }, "deposit": { "$ref": "#/components/schemas/PredictionWithdrawDeposit" }, "bridge": { "type": "object", "properties": { "observation": { "$ref": "#/components/schemas/PredictionBridgeObservation" } }, "required": [ "observation" ] } }, "required": [ "status", "operationId", "transfer", "deposit", "bridge" ], "description": "One attempted pUSD withdrawal with outgoing receipt, bridge observation and linked 1Click arrival kept separate. Only the linked deposit receipt establishes credited or refunded funds." }, "PredictionWithdrawTransfer": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "pending", "confirmed", "reverted", "uncertain" ] }, "transactionHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" } }, "required": [ "state" ] }, "PredictionWithdrawDeposit": { "type": "object", "properties": { "depositId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "incomplete", "processing", "credited", "refunded", "unknown", "expired", "failed" ] }, "receipt": { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the outcome was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Whether the transfer was credited or refunded." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What arrived at the address." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the agent wallet was credited; zero when all of it was refunded." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What went back to the agent wallet uncredited, such as a transfer below the minimum." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The transfers that paid the address, on the network they were sent on." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The refund's ledger identifiers, when they were reported." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] } }, "required": [ "depositId", "state" ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Stream a conversation's events 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. `GET /v1/users/{userId}/conversations/{conversationId}/stream` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ] ``` ## Query parameters ```json [ { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "cursor", "required": false, "description": "Replay saved events after this `seq`; omit it or send 0 to replay all of them. A `Last-Event-ID` header takes precedence on reconnect." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/conversations/YOUR_CONVERSATION_ID/stream' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A `text/event-stream` of conversation events. Each frame's SSE `id` is the event's `seq` (saved events only), `event` is the `FinEvent` type, and `data` is `{ delivery, seq, payload }`: `delivery: "durable"` for a saved event (with `seq` and `requestId`), or `delivery: "live"` for live-only text such as `agent.text_delta` (no `seq`, never replayed). Resume with the `Last-Event-ID` header or `?cursor=`. ```json { "description": "A `text/event-stream` of conversation events. Each frame's SSE `id` is the event's `seq` (saved events only), `event` is the `FinEvent` type, and `data` is `{ delivery, seq, payload }`: `delivery: \"durable\"` for a saved event (with `seq` and `requestId`), or `delivery: \"live\"` for live-only text such as `agent.text_delta` (no `seq`, never replayed). Resume with the `Last-Event-ID` header or `?cursor=`.", "content": { "text/event-stream": { "schema": { "type": "string" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `stream_capacity` — the partner, user or replica has no free stream capacity; honour `Retry-After` ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `stream_capacity` — the partner, user or replica has no free stream capacity; honour `Retry-After`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "events.stream", "summary": "Stream a conversation's events", "tags": [ "events" ], "description": "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.", "parameters": [ { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "cursor", "required": false, "description": "Replay saved events after this `seq`; omit it or send 0 to replay all of them. A `Last-Event-ID` header takes precedence on reconnect." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "conversationId", "required": true, "description": "The conversation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A `text/event-stream` of conversation events. Each frame's SSE `id` is the event's `seq` (saved events only), `event` is the `FinEvent` type, and `data` is `{ delivery, seq, payload }`: `delivery: \"durable\"` for a saved event (with `seq` and `requestId`), or `delivery: \"live\"` for live-only text such as `agent.text_delta` (no `seq`, never replayed). Resume with the `Last-Event-ID` header or `?cursor=`.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `stream_capacity` — the partner, user or replica has no free stream capacity; honour `Retry-After`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Start a run 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. `POST /v1/users/{userId}/runs` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": false, "description": "Optional. A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. Without it, a retry creates a second one." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation to send the message to." }, "text": { "type": "string", "minLength": 1, "maxLength": 32768, "description": "The user's message to the agent, up to 32768 characters." }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "description": "The strict terminal output contract validated and frozen during admission.", "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "What the terminal result means, shown beside the run's output.", "type": "string", "maxLength": 4096 }, "schema": { "description": "A bounded, strict JSON Schema object (`type: \"object\"`, `additionalProperties: false`) the run's terminal output must satisfy." } }, "required": [ "name", "schema" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Bounds on this run beyond its seed text: which tools it may reach, and its terminal output contract." }, "context": { "type": "object", "properties": { "timeZone": { "description": "The user's time zone as an IANA name, such as `America/New_York`: in a browser, `Intl.DateTimeFormat().resolvedOptions().timeZone`. The agent reads times in this message, like 9am, in this zone; without it, the agent asks the user.", "type": "string", "maxLength": 64, "pattern": "^[A-Za-z][\\w+-]*(?:\\/[\\w+-]+)*$" }, "renders": { "description": "What your app draws itself from this conversation, so the agent leaves those facts to it instead of repeating them: `receipts` for trades from `intents.settlement` events, `automations` for an automation from the automation tools' results, `balances` for the agent wallet from `intents_balances` results, `orders` for limit orders from the order tools' results, `contacts` for the user's saved contacts from `contacts_list` results, `grids` for grids from the `grid_create` and `intents_grids` results, and `research` for the research reads (`market_sentiment`, `market_derivatives`, `market_news`, `market_screen`, `macro_series` and `protocol_fundamentals`) from their results. Add `placement` when your app draws a read's card only where the reply places it: the agent then writes each finding as soon as it has it and puts a `[card r7k2q]` line after the sentence the card supports, naming the card from that read's call id (`replyCardName`), at most three a turn. Add `show` when your app draws a read's card where the agent's `show_cards` call stands instead (as `threadTurns` does): the agent is then offered `show_cards`, which names up to three cards a turn by the same names and writes no card line; a message that carries `show` ignores `placement`. Add `solana_sell_many` when your app draws a multi-coin Solana sale's approval card and outcome: only then is the agent offered the `solana_sell_many` tool, which sells two to six Solana coins under one approval; without it the agent proposes one `solana_sell` per coin. Add `deposit` when your app draws a deposit the user can make in place from a `deposit_request` result (what is missing for their request: `purpose`, `symbol`, `needed`, `held`, `short`): only then is the agent offered `deposit_request`, which it calls when the agent wallet cannot cover what the user asked for; without it the agent says what is missing in words. Add `share` when your app lets the user share an answer publicly: the agent then ends an answer that reports what it read with a `share` fenced block of up to three lines a stranger can read with only the question beside them (the finding first, then what backs it with its figures, never the user's own), which `splitReplyNextSteps` returns as `shareLines` and leaves out of the body. Leave `placement` and `show` out when your app shows only the agent's text: the agent then sums each one up in a line or two.", "maxItems": 12, "type": "array", "items": { "type": "string", "enum": [ "receipts", "automations", "balances", "orders", "contacts", "research", "placement", "show", "solana_sell_many", "deposit", "share", "grids" ] } }, "contacts": { "description": "The user's saved contacts, up to 200 and 64 KiB, so the agent can find \"Alice\" when the user asks to pay her. Send them from your server with every message: the agent reads only this message's contacts, and without them it asks the user for an address. Names and addresses are user-entered and treated as untrusted data. A contact authorizes nothing: the user still approves the exact address and network on the approval card.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$", "description": "Your app's id for this contact." }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The name the user saved, up to 64 characters." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$", "description": "The saved address, exactly as stored, such as `alice.near` or `0x…`." }, "network": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[a-z0-9][a-z0-9_-]*$", "description": "The network the address is on, as your app names it: `eth`, `base`, `near`, `solana` or `near_intents`." } }, "required": [ "id", "name", "address", "network" ], "additionalProperties": false } }, "perpsAllowed": { "description": "Whether your app allows this user to open or increase perpetuals exposure in their current region. Send a boolean with each message that may fund perpetuals; without true, funding is refused. Exits remain available. The latest reported value is saved per user, and a retry must send the original value.", "type": "boolean" }, "country": { "description": "The country the user is sending this message from, as an uppercase ISO 3166-1 alpha-2 code such as `GB`, resolved by your server from the request (your edge's IP geolocation), never taken from the browser. Tokenized stocks are offered only to a message that reports a country where they are available; without it the agent cannot trade them.", "type": "string", "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false, "description": "What the user's app knows about the user as they send this message. It applies to this message only, so send it with every message." } }, "required": [ "conversationId", "text" ], "additionalProperties": false } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/runs' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 202 The run, just started; the same run again when this `Idempotency-Key` already started one. ```json { "description": "The run, just started; the same run again when this `Idempotency-Key` already started one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted - `profile_unknown_tool` — `profile.tools` names a tool this deployment does not have ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `profile_unknown_tool` — `profile.tools` names a tool this deployment does not have", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request - `run_active` — a run already holds this conversation - `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed ```json { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `run_active` — a run already holds this conversation\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 410 The resource still exists and stays readable, but can no longer take this request. - `conversation_deleted` — the conversation was deleted; its history stays readable ```json { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `conversation_deleted` — the conversation was deleted; its history stays readable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it - `execution_capacity` — no capacity is free to run this right now; honour `Retry-After` - `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again - `deployment_paused` — an operator paused this kind of work for the deployment; try again later ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `deployment_paused` — an operator paused this kind of work for the deployment; try again later", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "runs.start", "summary": "Start a run", "tags": [ "runs" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation to send the message to." }, "text": { "type": "string", "minLength": 1, "maxLength": 32768, "description": "The user's message to the agent, up to 32768 characters." }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "description": "The strict terminal output contract validated and frozen during admission.", "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "What the terminal result means, shown beside the run's output.", "type": "string", "maxLength": 4096 }, "schema": { "description": "A bounded, strict JSON Schema object (`type: \"object\"`, `additionalProperties: false`) the run's terminal output must satisfy." } }, "required": [ "name", "schema" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Bounds on this run beyond its seed text: which tools it may reach, and its terminal output contract." }, "context": { "type": "object", "properties": { "timeZone": { "description": "The user's time zone as an IANA name, such as `America/New_York`: in a browser, `Intl.DateTimeFormat().resolvedOptions().timeZone`. The agent reads times in this message, like 9am, in this zone; without it, the agent asks the user.", "type": "string", "maxLength": 64, "pattern": "^[A-Za-z][\\w+-]*(?:\\/[\\w+-]+)*$" }, "renders": { "description": "What your app draws itself from this conversation, so the agent leaves those facts to it instead of repeating them: `receipts` for trades from `intents.settlement` events, `automations` for an automation from the automation tools' results, `balances` for the agent wallet from `intents_balances` results, `orders` for limit orders from the order tools' results, `contacts` for the user's saved contacts from `contacts_list` results, `grids` for grids from the `grid_create` and `intents_grids` results, and `research` for the research reads (`market_sentiment`, `market_derivatives`, `market_news`, `market_screen`, `macro_series` and `protocol_fundamentals`) from their results. Add `placement` when your app draws a read's card only where the reply places it: the agent then writes each finding as soon as it has it and puts a `[card r7k2q]` line after the sentence the card supports, naming the card from that read's call id (`replyCardName`), at most three a turn. Add `show` when your app draws a read's card where the agent's `show_cards` call stands instead (as `threadTurns` does): the agent is then offered `show_cards`, which names up to three cards a turn by the same names and writes no card line; a message that carries `show` ignores `placement`. Add `solana_sell_many` when your app draws a multi-coin Solana sale's approval card and outcome: only then is the agent offered the `solana_sell_many` tool, which sells two to six Solana coins under one approval; without it the agent proposes one `solana_sell` per coin. Add `deposit` when your app draws a deposit the user can make in place from a `deposit_request` result (what is missing for their request: `purpose`, `symbol`, `needed`, `held`, `short`): only then is the agent offered `deposit_request`, which it calls when the agent wallet cannot cover what the user asked for; without it the agent says what is missing in words. Add `share` when your app lets the user share an answer publicly: the agent then ends an answer that reports what it read with a `share` fenced block of up to three lines a stranger can read with only the question beside them (the finding first, then what backs it with its figures, never the user's own), which `splitReplyNextSteps` returns as `shareLines` and leaves out of the body. Leave `placement` and `show` out when your app shows only the agent's text: the agent then sums each one up in a line or two.", "maxItems": 12, "type": "array", "items": { "type": "string", "enum": [ "receipts", "automations", "balances", "orders", "contacts", "research", "placement", "show", "solana_sell_many", "deposit", "share", "grids" ] } }, "contacts": { "description": "The user's saved contacts, up to 200 and 64 KiB, so the agent can find \"Alice\" when the user asks to pay her. Send them from your server with every message: the agent reads only this message's contacts, and without them it asks the user for an address. Names and addresses are user-entered and treated as untrusted data. A contact authorizes nothing: the user still approves the exact address and network on the approval card.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$", "description": "Your app's id for this contact." }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The name the user saved, up to 64 characters." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$", "description": "The saved address, exactly as stored, such as `alice.near` or `0x…`." }, "network": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[a-z0-9][a-z0-9_-]*$", "description": "The network the address is on, as your app names it: `eth`, `base`, `near`, `solana` or `near_intents`." } }, "required": [ "id", "name", "address", "network" ], "additionalProperties": false } }, "perpsAllowed": { "description": "Whether your app allows this user to open or increase perpetuals exposure in their current region. Send a boolean with each message that may fund perpetuals; without true, funding is refused. Exits remain available. The latest reported value is saved per user, and a retry must send the original value.", "type": "boolean" }, "country": { "description": "The country the user is sending this message from, as an uppercase ISO 3166-1 alpha-2 code such as `GB`, resolved by your server from the request (your edge's IP geolocation), never taken from the browser. Tokenized stocks are offered only to a message that reports a country where they are available; without it the agent cannot trade them.", "type": "string", "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false, "description": "What the user's app knows about the user as they send this message. It applies to this message only, so send it with every message." } }, "required": [ "conversationId", "text" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": false, "description": "Optional. A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. Without it, a retry creates a second one." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "202": { "description": "The run, just started; the same run again when this `Idempotency-Key` already started one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `profile_unknown_tool` — `profile.tools` names a tool this deployment does not have", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `run_active` — a run already holds this conversation\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "410": { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `conversation_deleted` — the conversation was deleted; its history stays readable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `deployment_paused` — an operator paused this kind of work for the deployment; try again later", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "Run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id. It stays the same while the run pauses for approvals and resumes." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "input": { "description": "The user's message that started the run; null only for old runs that did not keep it.", "type": [ "string", "null" ] }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "Meaning of this terminal output contract.", "type": "string", "maxLength": 4096 }, "schema": { "description": "The immutable strict object schema that the terminal output must satisfy.", "$ref": "#/components/schemas/RunOutputObjectSchema" } }, "required": [ "name", "schema" ], "description": "The immutable admitted output contract, readable without invoking its admission transform." }, "modelId": { "description": "The reviewed provider model pinned by trusted admission; absent for historical default selection.", "type": "string", "minLength": 1, "maxLength": 200 } }, "description": "The tools, output contract and model the run started with. They never change." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the run started." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the run ended; null while it is running or paused for human input or approval." }, "status": { "$ref": "#/components/schemas/RunStatus" }, "output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "null" } ], "description": "The run's terminal structured result, once it has one under its `outputContract`; null otherwise." }, "response": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "description": "The agent's full reply, never shortened." }, "eventSeq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The `seq` of the event that carries the reply." }, "completeness": { "type": "string", "enum": [ "complete", "partial" ], "description": "`complete` when the run completed; `partial` when it was stopped or failed before finishing." } }, "required": [ "text", "eventSeq", "completeness" ] }, { "type": "null" } ], "description": "The agent's reply since the run last started, resumed or was steered, once it has one." }, "error": { "description": "Why the run failed or was stopped; null when neither happened.", "type": [ "string", "null" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "model_timeout", "model_invalid_output", "execution_deadline", "provider_rate_limit", "provider_unavailable", "provider_authentication", "internal_error", "context_too_large", "daily_budget_exhausted", "monthly_budget_exhausted", "budget_frozen", "partner_daily_budget_exhausted", "partner_monthly_budget_exhausted", "unknown" ], "description": "Why the execution failed: `model_timeout` (the model was too slow to respond), `execution_deadline` (the run's active time limit elapsed before it finished), `provider_rate_limit` or `provider_unavailable` (classified from HTTP status or a connection/body-read failure observed by the host), `model_invalid_output` (terminal structured output still failed its required format after bounded repair), `context_too_large` (the request stayed over the model's context window after the host condensed earlier history and retried once), `daily_budget_exhausted`, `monthly_budget_exhausted` or `budget_frozen` (the user's AI budget for the UTC day or month, or an operator's freeze on it, left no room for the run's next model request), `partner_daily_budget_exhausted` or `partner_monthly_budget_exhausted` (the partner account's AI spend limit for the UTC day or month left no room for it), `internal_error` (a host-side fault), or `unknown` when nothing more specific was classified. A budget or spend-limit code means a limit stopped the run, not that the model failed; trying again fails the same way until the limit clears. A raised user budget or a lifted freeze applies at once; a raised partner limit applies from the next UTC day or month, because the open period keeps the cap it started with." }, "stage": { "type": "string", "enum": [ "model_request", "tool_execution", "finalization" ], "description": "Which phase of the run was executing when it failed: `model_request` while calling or awaiting the model provider, `tool_execution` while running or resuming a tool call, or `finalization` while settling the run's output and accounting after the model finished." }, "providerMessage": { "description": "The model provider's own error text, when one was available: credential values are redacted and it is cut to 256 characters, but it is not a content classifier, so other sensitive detail may remain. Treat it as diagnostic context only — never branch on it, and review before showing it to an end user.", "type": "string", "minLength": 1, "maxLength": 256 }, "diagnosticReference": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This failed run's own id, repeated here as one field to cite when asking support to check the host's internal logs for this execution; it carries no meaning beyond that." }, "effectWarning": { "type": "string", "const": "Earlier actions may have completed. Partial output does not prove success or a delivery failure. Check receipts before retrying; retrying may repeat actions.", "description": "This build's fixed caution: earlier actions may already have run, so partial output alone never proves success, a delivery failure, or that retrying is free of duplicate effects." } }, "required": [ "code", "stage", "diagnosticReference", "effectWarning" ] }, { "type": "null" } ], "description": "Details of a failure, when recorded." }, "pendingApprovals": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "description": "The approvals this run is waiting on, oldest first." }, "pendingQuestions": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The questionnaire ids this run is waiting on, oldest first." }, "steers": { "type": "array", "items": { "$ref": "#/components/schemas/RunSteer" }, "description": "The messages the user sent this run while it worked, with Steer a run, oldest first; empty when they sent none." }, "feedback": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedback" }, { "type": "null" } ], "description": "The user's feedback on this run's reply; null until they send it." }, "origin": { "anyOf": [ { "type": "object", "properties": { "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run it carried out: its `id` in List an automation's runs." }, "name": { "type": "string", "description": "The automation's name when that automation run was recorded." } }, "required": [ "automationId", "automationRunId", "name" ] }, { "type": "null" } ], "description": "The automation that started this run; `null` for a run the user started with a message." }, "reads": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "account", "prices" ] }, "description": "What the agent read while it worked, told by the tools whose calls completed: `account` (the user's own balances, holdings, orders or positions) and `prices` (market prices). Empty when it read neither." } }, "required": [ "id", "conversationId", "input", "profile", "startedAt", "endedAt", "status", "output", "response", "error", "failure", "pendingApprovals", "pendingQuestions", "steers", "feedback", "origin", "reads" ], "description": "The agent's work on one message: its status, the agent's reply once it finishes, any approvals or questionnaires it is waiting on, the messages the user sent it while it worked, and the user's feedback on the reply." }, "RunOutputObjectSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "JSON Schema type keyword: object." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/RunOutputSchemaNode" }, "description": "Named fields and their strict schemas." }, "required": { "type": "array", "items": { "type": "string" }, "description": "Every declared property is required exactly once." }, "additionalProperties": { "type": "boolean", "const": false, "description": "Always false; undeclared properties are rejected." } }, "required": [ "type", "properties", "required", "additionalProperties" ], "description": "A strict object with all declared properties required and no extra properties." }, "RunOutputSchemaNode": { "description": "A bounded node in the strict JSON Schema supported for run output.", "$ref": "#/components/schemas/schema0" }, "schema0": { "anyOf": [ { "$ref": "#/components/schemas/RunOutputObjectSchema" }, { "type": "object", "properties": { "type": { "type": "string", "const": "array", "description": "JSON Schema type keyword: array." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "items": { "description": "Schema every array entry must satisfy.", "$ref": "#/components/schemas/RunOutputSchemaNode" }, "minItems": { "description": "Inclusive minimum number of array entries.", "type": "number" }, "maxItems": { "description": "Inclusive maximum number of array entries.", "type": "number" } }, "required": [ "type", "items" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "JSON Schema type keyword: string." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "string" } }, "minLength": { "description": "Inclusive minimum string length.", "type": "number" }, "maxLength": { "description": "Inclusive maximum string length.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "JSON Schema type keyword: number." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "JSON Schema type keyword: integer." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "JSON Schema type keyword: boolean." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "boolean" } } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "null", "description": "JSON Schema type keyword: null." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" } }, "required": [ "type" ] } ], "description": "One supported strict JSON Schema node: object, array, string, number, integer, boolean or null." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "RunSteer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The message's id; the `run.steered` event that delivers it names it." }, "text": { "type": "string", "description": "The message, as the user sent it." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dropped" ], "description": "`pending` until the agent reads it at its next step; `delivered` once it has; `dropped` when the run ended before the agent read it, so it was never acted on. Send a dropped message again with Start a run." }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user sent it." }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the agent read it; null until it is `delivered`." } }, "required": [ "id", "text", "status", "sentAt", "deliveredAt" ], "description": "A message the user sent a run while it was working, and whether the agent read it." }, "RunFeedback": { "type": "object", "properties": { "rating": { "$ref": "#/components/schemas/RunFeedbackRating" }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedbackReason" }, { "type": "null" } ], "description": "Why the user rated it down; null when they gave no reason or rated it `up`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user first sent feedback on this run's reply." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the feedback last changed; the same as `createdAt` until it does." } }, "required": [ "rating", "reason", "createdAt", "updatedAt" ], "description": "The user's feedback on one run's reply: a thumbs-up or thumbs-down, and why." }, "RunFeedbackRating": { "type": "string", "enum": [ "up", "down" ], "description": "How the user rated the reply: `up` for a thumbs-up, `down` for a thumbs-down." }, "RunFeedbackReason": { "type": "string", "enum": [ "wrong", "unhelpful", "slow", "unsafe", "other" ], "description": "Why the user rated the reply down: `wrong` it was incorrect, `unhelpful` it did not do what was asked, `slow` it took too long, `unsafe` it was risky or inappropriate, `other` none of these." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List runs 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 /v1/users/{userId}/runs` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "conversationId", "required": false, "description": "Only this conversation's runs; omit for all of the user's runs." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/runs' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of runs. ```json { "description": "A page of runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "runs.list", "summary": "List runs", "tags": [ "runs" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "conversationId", "required": false, "description": "Only this conversation's runs; omit for all of the user's runs." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id. It stays the same while the run pauses for approvals and resumes." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "input": { "description": "The user's message that started the run; null only for old runs that did not keep it.", "type": [ "string", "null" ] }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "Meaning of this terminal output contract.", "type": "string", "maxLength": 4096 }, "schema": { "description": "The immutable strict object schema that the terminal output must satisfy.", "$ref": "#/components/schemas/RunOutputObjectSchema" } }, "required": [ "name", "schema" ], "description": "The immutable admitted output contract, readable without invoking its admission transform." }, "modelId": { "description": "The reviewed provider model pinned by trusted admission; absent for historical default selection.", "type": "string", "minLength": 1, "maxLength": 200 } }, "description": "The tools, output contract and model the run started with. They never change." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the run started." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the run ended; null while it is running or paused for human input or approval." }, "status": { "$ref": "#/components/schemas/RunStatus" }, "output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "null" } ], "description": "The run's terminal structured result, once it has one under its `outputContract`; null otherwise." }, "response": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "description": "The agent's full reply, never shortened." }, "eventSeq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The `seq` of the event that carries the reply." }, "completeness": { "type": "string", "enum": [ "complete", "partial" ], "description": "`complete` when the run completed; `partial` when it was stopped or failed before finishing." } }, "required": [ "text", "eventSeq", "completeness" ] }, { "type": "null" } ], "description": "The agent's reply since the run last started, resumed or was steered, once it has one." }, "error": { "description": "Why the run failed or was stopped; null when neither happened.", "type": [ "string", "null" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "model_timeout", "model_invalid_output", "execution_deadline", "provider_rate_limit", "provider_unavailable", "provider_authentication", "internal_error", "context_too_large", "daily_budget_exhausted", "monthly_budget_exhausted", "budget_frozen", "partner_daily_budget_exhausted", "partner_monthly_budget_exhausted", "unknown" ], "description": "Why the execution failed: `model_timeout` (the model was too slow to respond), `execution_deadline` (the run's active time limit elapsed before it finished), `provider_rate_limit` or `provider_unavailable` (classified from HTTP status or a connection/body-read failure observed by the host), `model_invalid_output` (terminal structured output still failed its required format after bounded repair), `context_too_large` (the request stayed over the model's context window after the host condensed earlier history and retried once), `daily_budget_exhausted`, `monthly_budget_exhausted` or `budget_frozen` (the user's AI budget for the UTC day or month, or an operator's freeze on it, left no room for the run's next model request), `partner_daily_budget_exhausted` or `partner_monthly_budget_exhausted` (the partner account's AI spend limit for the UTC day or month left no room for it), `internal_error` (a host-side fault), or `unknown` when nothing more specific was classified. A budget or spend-limit code means a limit stopped the run, not that the model failed; trying again fails the same way until the limit clears. A raised user budget or a lifted freeze applies at once; a raised partner limit applies from the next UTC day or month, because the open period keeps the cap it started with." }, "stage": { "type": "string", "enum": [ "model_request", "tool_execution", "finalization" ], "description": "Which phase of the run was executing when it failed: `model_request` while calling or awaiting the model provider, `tool_execution` while running or resuming a tool call, or `finalization` while settling the run's output and accounting after the model finished." }, "providerMessage": { "description": "The model provider's own error text, when one was available: credential values are redacted and it is cut to 256 characters, but it is not a content classifier, so other sensitive detail may remain. Treat it as diagnostic context only — never branch on it, and review before showing it to an end user.", "type": "string", "minLength": 1, "maxLength": 256 }, "diagnosticReference": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This failed run's own id, repeated here as one field to cite when asking support to check the host's internal logs for this execution; it carries no meaning beyond that." }, "effectWarning": { "type": "string", "const": "Earlier actions may have completed. Partial output does not prove success or a delivery failure. Check receipts before retrying; retrying may repeat actions.", "description": "This build's fixed caution: earlier actions may already have run, so partial output alone never proves success, a delivery failure, or that retrying is free of duplicate effects." } }, "required": [ "code", "stage", "diagnosticReference", "effectWarning" ] }, { "type": "null" } ], "description": "Details of a failure, when recorded." }, "pendingApprovals": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "description": "The approvals this run is waiting on, oldest first." }, "pendingQuestions": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The questionnaire ids this run is waiting on, oldest first." }, "steers": { "type": "array", "items": { "$ref": "#/components/schemas/RunSteer" }, "description": "The messages the user sent this run while it worked, with Steer a run, oldest first; empty when they sent none." }, "feedback": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedback" }, { "type": "null" } ], "description": "The user's feedback on this run's reply; null until they send it." }, "origin": { "anyOf": [ { "type": "object", "properties": { "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run it carried out: its `id` in List an automation's runs." }, "name": { "type": "string", "description": "The automation's name when that automation run was recorded." } }, "required": [ "automationId", "automationRunId", "name" ] }, { "type": "null" } ], "description": "The automation that started this run; `null` for a run the user started with a message." }, "reads": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "account", "prices" ] }, "description": "What the agent read while it worked, told by the tools whose calls completed: `account` (the user's own balances, holdings, orders or positions) and `prices` (market prices). Empty when it read neither." } }, "required": [ "id", "conversationId", "input", "profile", "startedAt", "endedAt", "status", "output", "response", "error", "failure", "pendingApprovals", "pendingQuestions", "steers", "feedback", "origin", "reads" ], "description": "The agent's work on one message: its status, the agent's reply once it finishes, any approvals or questionnaires it is waiting on, the messages the user sent it while it worked, and the user's feedback on the reply." }, "RunOutputObjectSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "JSON Schema type keyword: object." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/RunOutputSchemaNode" }, "description": "Named fields and their strict schemas." }, "required": { "type": "array", "items": { "type": "string" }, "description": "Every declared property is required exactly once." }, "additionalProperties": { "type": "boolean", "const": false, "description": "Always false; undeclared properties are rejected." } }, "required": [ "type", "properties", "required", "additionalProperties" ], "description": "A strict object with all declared properties required and no extra properties." }, "RunOutputSchemaNode": { "description": "A bounded node in the strict JSON Schema supported for run output.", "$ref": "#/components/schemas/schema0" }, "schema0": { "anyOf": [ { "$ref": "#/components/schemas/RunOutputObjectSchema" }, { "type": "object", "properties": { "type": { "type": "string", "const": "array", "description": "JSON Schema type keyword: array." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "items": { "description": "Schema every array entry must satisfy.", "$ref": "#/components/schemas/RunOutputSchemaNode" }, "minItems": { "description": "Inclusive minimum number of array entries.", "type": "number" }, "maxItems": { "description": "Inclusive maximum number of array entries.", "type": "number" } }, "required": [ "type", "items" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "JSON Schema type keyword: string." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "string" } }, "minLength": { "description": "Inclusive minimum string length.", "type": "number" }, "maxLength": { "description": "Inclusive maximum string length.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "JSON Schema type keyword: number." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "JSON Schema type keyword: integer." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "JSON Schema type keyword: boolean." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "boolean" } } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "null", "description": "JSON Schema type keyword: null." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" } }, "required": [ "type" ] } ], "description": "One supported strict JSON Schema node: object, array, string, number, integer, boolean or null." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "RunSteer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The message's id; the `run.steered` event that delivers it names it." }, "text": { "type": "string", "description": "The message, as the user sent it." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dropped" ], "description": "`pending` until the agent reads it at its next step; `delivered` once it has; `dropped` when the run ended before the agent read it, so it was never acted on. Send a dropped message again with Start a run." }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user sent it." }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the agent read it; null until it is `delivered`." } }, "required": [ "id", "text", "status", "sentAt", "deliveredAt" ], "description": "A message the user sent a run while it was working, and whether the agent read it." }, "RunFeedback": { "type": "object", "properties": { "rating": { "$ref": "#/components/schemas/RunFeedbackRating" }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedbackReason" }, { "type": "null" } ], "description": "Why the user rated it down; null when they gave no reason or rated it `up`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user first sent feedback on this run's reply." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the feedback last changed; the same as `createdAt` until it does." } }, "required": [ "rating", "reason", "createdAt", "updatedAt" ], "description": "The user's feedback on one run's reply: a thumbs-up or thumbs-down, and why." }, "RunFeedbackRating": { "type": "string", "enum": [ "up", "down" ], "description": "How the user rated the reply: `up` for a thumbs-up, `down` for a thumbs-down." }, "RunFeedbackReason": { "type": "string", "enum": [ "wrong", "unhelpful", "slow", "unsafe", "other" ], "description": "Why the user rated the reply down: `wrong` it was incorrect, `unhelpful` it did not do what was asked, `slow` it took too long, `unsafe` it was risky or inappropriate, `other` none of these." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a run 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. `GET /v1/users/{userId}/runs/{runId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/runs/YOUR_RUN_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The run. ```json { "description": "The run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "runs.get", "summary": "Get a run", "tags": [ "runs" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id. It stays the same while the run pauses for approvals and resumes." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "input": { "description": "The user's message that started the run; null only for old runs that did not keep it.", "type": [ "string", "null" ] }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "Meaning of this terminal output contract.", "type": "string", "maxLength": 4096 }, "schema": { "description": "The immutable strict object schema that the terminal output must satisfy.", "$ref": "#/components/schemas/RunOutputObjectSchema" } }, "required": [ "name", "schema" ], "description": "The immutable admitted output contract, readable without invoking its admission transform." }, "modelId": { "description": "The reviewed provider model pinned by trusted admission; absent for historical default selection.", "type": "string", "minLength": 1, "maxLength": 200 } }, "description": "The tools, output contract and model the run started with. They never change." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the run started." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the run ended; null while it is running or paused for human input or approval." }, "status": { "$ref": "#/components/schemas/RunStatus" }, "output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "null" } ], "description": "The run's terminal structured result, once it has one under its `outputContract`; null otherwise." }, "response": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "description": "The agent's full reply, never shortened." }, "eventSeq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The `seq` of the event that carries the reply." }, "completeness": { "type": "string", "enum": [ "complete", "partial" ], "description": "`complete` when the run completed; `partial` when it was stopped or failed before finishing." } }, "required": [ "text", "eventSeq", "completeness" ] }, { "type": "null" } ], "description": "The agent's reply since the run last started, resumed or was steered, once it has one." }, "error": { "description": "Why the run failed or was stopped; null when neither happened.", "type": [ "string", "null" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "model_timeout", "model_invalid_output", "execution_deadline", "provider_rate_limit", "provider_unavailable", "provider_authentication", "internal_error", "context_too_large", "daily_budget_exhausted", "monthly_budget_exhausted", "budget_frozen", "partner_daily_budget_exhausted", "partner_monthly_budget_exhausted", "unknown" ], "description": "Why the execution failed: `model_timeout` (the model was too slow to respond), `execution_deadline` (the run's active time limit elapsed before it finished), `provider_rate_limit` or `provider_unavailable` (classified from HTTP status or a connection/body-read failure observed by the host), `model_invalid_output` (terminal structured output still failed its required format after bounded repair), `context_too_large` (the request stayed over the model's context window after the host condensed earlier history and retried once), `daily_budget_exhausted`, `monthly_budget_exhausted` or `budget_frozen` (the user's AI budget for the UTC day or month, or an operator's freeze on it, left no room for the run's next model request), `partner_daily_budget_exhausted` or `partner_monthly_budget_exhausted` (the partner account's AI spend limit for the UTC day or month left no room for it), `internal_error` (a host-side fault), or `unknown` when nothing more specific was classified. A budget or spend-limit code means a limit stopped the run, not that the model failed; trying again fails the same way until the limit clears. A raised user budget or a lifted freeze applies at once; a raised partner limit applies from the next UTC day or month, because the open period keeps the cap it started with." }, "stage": { "type": "string", "enum": [ "model_request", "tool_execution", "finalization" ], "description": "Which phase of the run was executing when it failed: `model_request` while calling or awaiting the model provider, `tool_execution` while running or resuming a tool call, or `finalization` while settling the run's output and accounting after the model finished." }, "providerMessage": { "description": "The model provider's own error text, when one was available: credential values are redacted and it is cut to 256 characters, but it is not a content classifier, so other sensitive detail may remain. Treat it as diagnostic context only — never branch on it, and review before showing it to an end user.", "type": "string", "minLength": 1, "maxLength": 256 }, "diagnosticReference": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This failed run's own id, repeated here as one field to cite when asking support to check the host's internal logs for this execution; it carries no meaning beyond that." }, "effectWarning": { "type": "string", "const": "Earlier actions may have completed. Partial output does not prove success or a delivery failure. Check receipts before retrying; retrying may repeat actions.", "description": "This build's fixed caution: earlier actions may already have run, so partial output alone never proves success, a delivery failure, or that retrying is free of duplicate effects." } }, "required": [ "code", "stage", "diagnosticReference", "effectWarning" ] }, { "type": "null" } ], "description": "Details of a failure, when recorded." }, "pendingApprovals": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "description": "The approvals this run is waiting on, oldest first." }, "pendingQuestions": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The questionnaire ids this run is waiting on, oldest first." }, "steers": { "type": "array", "items": { "$ref": "#/components/schemas/RunSteer" }, "description": "The messages the user sent this run while it worked, with Steer a run, oldest first; empty when they sent none." }, "feedback": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedback" }, { "type": "null" } ], "description": "The user's feedback on this run's reply; null until they send it." }, "origin": { "anyOf": [ { "type": "object", "properties": { "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run it carried out: its `id` in List an automation's runs." }, "name": { "type": "string", "description": "The automation's name when that automation run was recorded." } }, "required": [ "automationId", "automationRunId", "name" ] }, { "type": "null" } ], "description": "The automation that started this run; `null` for a run the user started with a message." }, "reads": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "account", "prices" ] }, "description": "What the agent read while it worked, told by the tools whose calls completed: `account` (the user's own balances, holdings, orders or positions) and `prices` (market prices). Empty when it read neither." } }, "required": [ "id", "conversationId", "input", "profile", "startedAt", "endedAt", "status", "output", "response", "error", "failure", "pendingApprovals", "pendingQuestions", "steers", "feedback", "origin", "reads" ], "description": "The agent's work on one message: its status, the agent's reply once it finishes, any approvals or questionnaires it is waiting on, the messages the user sent it while it worked, and the user's feedback on the reply." }, "RunOutputObjectSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "JSON Schema type keyword: object." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/RunOutputSchemaNode" }, "description": "Named fields and their strict schemas." }, "required": { "type": "array", "items": { "type": "string" }, "description": "Every declared property is required exactly once." }, "additionalProperties": { "type": "boolean", "const": false, "description": "Always false; undeclared properties are rejected." } }, "required": [ "type", "properties", "required", "additionalProperties" ], "description": "A strict object with all declared properties required and no extra properties." }, "RunOutputSchemaNode": { "description": "A bounded node in the strict JSON Schema supported for run output.", "$ref": "#/components/schemas/schema0" }, "schema0": { "anyOf": [ { "$ref": "#/components/schemas/RunOutputObjectSchema" }, { "type": "object", "properties": { "type": { "type": "string", "const": "array", "description": "JSON Schema type keyword: array." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "items": { "description": "Schema every array entry must satisfy.", "$ref": "#/components/schemas/RunOutputSchemaNode" }, "minItems": { "description": "Inclusive minimum number of array entries.", "type": "number" }, "maxItems": { "description": "Inclusive maximum number of array entries.", "type": "number" } }, "required": [ "type", "items" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "JSON Schema type keyword: string." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "string" } }, "minLength": { "description": "Inclusive minimum string length.", "type": "number" }, "maxLength": { "description": "Inclusive maximum string length.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "JSON Schema type keyword: number." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "JSON Schema type keyword: integer." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "JSON Schema type keyword: boolean." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "boolean" } } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "null", "description": "JSON Schema type keyword: null." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" } }, "required": [ "type" ] } ], "description": "One supported strict JSON Schema node: object, array, string, number, integer, boolean or null." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "RunSteer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The message's id; the `run.steered` event that delivers it names it." }, "text": { "type": "string", "description": "The message, as the user sent it." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dropped" ], "description": "`pending` until the agent reads it at its next step; `delivered` once it has; `dropped` when the run ended before the agent read it, so it was never acted on. Send a dropped message again with Start a run." }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user sent it." }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the agent read it; null until it is `delivered`." } }, "required": [ "id", "text", "status", "sentAt", "deliveredAt" ], "description": "A message the user sent a run while it was working, and whether the agent read it." }, "RunFeedback": { "type": "object", "properties": { "rating": { "$ref": "#/components/schemas/RunFeedbackRating" }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedbackReason" }, { "type": "null" } ], "description": "Why the user rated it down; null when they gave no reason or rated it `up`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user first sent feedback on this run's reply." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the feedback last changed; the same as `createdAt` until it does." } }, "required": [ "rating", "reason", "createdAt", "updatedAt" ], "description": "The user's feedback on one run's reply: a thumbs-up or thumbs-down, and why." }, "RunFeedbackRating": { "type": "string", "enum": [ "up", "down" ], "description": "How the user rated the reply: `up` for a thumbs-up, `down` for a thumbs-down." }, "RunFeedbackReason": { "type": "string", "enum": [ "wrong", "unhelpful", "slow", "unsafe", "other" ], "description": "Why the user rated the reply down: `wrong` it was incorrect, `unhelpful` it did not do what was asked, `slow` it took too long, `unsafe` it was risky or inappropriate, `other` none of these." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Steer a run 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. `POST /v1/users/{userId}/runs/{runId}/steer` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": false, "description": "Optional. A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. Without it, a retry creates a second one." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 32768, "description": "The user's new message for the working agent, up to 32768 characters." } }, "required": [ "text" ], "additionalProperties": false }, "example": { "text": "Use 50 USDC instead of 100." } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/runs/YOUR_RUN_ID/steer' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "text": "Use 50 USDC instead of 100." }' ``` ## Responses ### 202 The run, with the message in its `steers`; the same run again when this `Idempotency-Key` already sent it. ```json { "description": "The run, with the message in its `steers`; the same run again when this `Idempotency-Key` already sent it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `steering_disabled` — steering a working run is not turned on for this user; send the message with Start a run once the run ends ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `steering_disabled` — steering a working run is not turned on for this user; send the message with Start a run once the run ends", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `run_not_active` — the run named in the path is not the conversation's live run - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `run_not_active` — the run named in the path is not the conversation's live run\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `execution_capacity` — no capacity is free to run this right now; honour `Retry-After` - `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again - `deployment_paused` — an operator paused this kind of work for the deployment; try again later ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `deployment_paused` — an operator paused this kind of work for the deployment; try again later", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "runs.steer", "summary": "Steer a run", "tags": [ "runs" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 32768, "description": "The user's new message for the working agent, up to 32768 characters." } }, "required": [ "text" ], "additionalProperties": false }, "example": { "text": "Use 50 USDC instead of 100." } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": false, "description": "Optional. A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. Without it, a retry creates a second one." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "202": { "description": "The run, with the message in its `steers`; the same run again when this `Idempotency-Key` already sent it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `steering_disabled` — steering a working run is not turned on for this user; send the message with Start a run once the run ends", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `run_not_active` — the run named in the path is not the conversation's live run\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `deployment_paused` — an operator paused this kind of work for the deployment; try again later", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "Run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id. It stays the same while the run pauses for approvals and resumes." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "input": { "description": "The user's message that started the run; null only for old runs that did not keep it.", "type": [ "string", "null" ] }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "Meaning of this terminal output contract.", "type": "string", "maxLength": 4096 }, "schema": { "description": "The immutable strict object schema that the terminal output must satisfy.", "$ref": "#/components/schemas/RunOutputObjectSchema" } }, "required": [ "name", "schema" ], "description": "The immutable admitted output contract, readable without invoking its admission transform." }, "modelId": { "description": "The reviewed provider model pinned by trusted admission; absent for historical default selection.", "type": "string", "minLength": 1, "maxLength": 200 } }, "description": "The tools, output contract and model the run started with. They never change." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the run started." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the run ended; null while it is running or paused for human input or approval." }, "status": { "$ref": "#/components/schemas/RunStatus" }, "output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "null" } ], "description": "The run's terminal structured result, once it has one under its `outputContract`; null otherwise." }, "response": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "description": "The agent's full reply, never shortened." }, "eventSeq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The `seq` of the event that carries the reply." }, "completeness": { "type": "string", "enum": [ "complete", "partial" ], "description": "`complete` when the run completed; `partial` when it was stopped or failed before finishing." } }, "required": [ "text", "eventSeq", "completeness" ] }, { "type": "null" } ], "description": "The agent's reply since the run last started, resumed or was steered, once it has one." }, "error": { "description": "Why the run failed or was stopped; null when neither happened.", "type": [ "string", "null" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "model_timeout", "model_invalid_output", "execution_deadline", "provider_rate_limit", "provider_unavailable", "provider_authentication", "internal_error", "context_too_large", "daily_budget_exhausted", "monthly_budget_exhausted", "budget_frozen", "partner_daily_budget_exhausted", "partner_monthly_budget_exhausted", "unknown" ], "description": "Why the execution failed: `model_timeout` (the model was too slow to respond), `execution_deadline` (the run's active time limit elapsed before it finished), `provider_rate_limit` or `provider_unavailable` (classified from HTTP status or a connection/body-read failure observed by the host), `model_invalid_output` (terminal structured output still failed its required format after bounded repair), `context_too_large` (the request stayed over the model's context window after the host condensed earlier history and retried once), `daily_budget_exhausted`, `monthly_budget_exhausted` or `budget_frozen` (the user's AI budget for the UTC day or month, or an operator's freeze on it, left no room for the run's next model request), `partner_daily_budget_exhausted` or `partner_monthly_budget_exhausted` (the partner account's AI spend limit for the UTC day or month left no room for it), `internal_error` (a host-side fault), or `unknown` when nothing more specific was classified. A budget or spend-limit code means a limit stopped the run, not that the model failed; trying again fails the same way until the limit clears. A raised user budget or a lifted freeze applies at once; a raised partner limit applies from the next UTC day or month, because the open period keeps the cap it started with." }, "stage": { "type": "string", "enum": [ "model_request", "tool_execution", "finalization" ], "description": "Which phase of the run was executing when it failed: `model_request` while calling or awaiting the model provider, `tool_execution` while running or resuming a tool call, or `finalization` while settling the run's output and accounting after the model finished." }, "providerMessage": { "description": "The model provider's own error text, when one was available: credential values are redacted and it is cut to 256 characters, but it is not a content classifier, so other sensitive detail may remain. Treat it as diagnostic context only — never branch on it, and review before showing it to an end user.", "type": "string", "minLength": 1, "maxLength": 256 }, "diagnosticReference": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This failed run's own id, repeated here as one field to cite when asking support to check the host's internal logs for this execution; it carries no meaning beyond that." }, "effectWarning": { "type": "string", "const": "Earlier actions may have completed. Partial output does not prove success or a delivery failure. Check receipts before retrying; retrying may repeat actions.", "description": "This build's fixed caution: earlier actions may already have run, so partial output alone never proves success, a delivery failure, or that retrying is free of duplicate effects." } }, "required": [ "code", "stage", "diagnosticReference", "effectWarning" ] }, { "type": "null" } ], "description": "Details of a failure, when recorded." }, "pendingApprovals": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "description": "The approvals this run is waiting on, oldest first." }, "pendingQuestions": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The questionnaire ids this run is waiting on, oldest first." }, "steers": { "type": "array", "items": { "$ref": "#/components/schemas/RunSteer" }, "description": "The messages the user sent this run while it worked, with Steer a run, oldest first; empty when they sent none." }, "feedback": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedback" }, { "type": "null" } ], "description": "The user's feedback on this run's reply; null until they send it." }, "origin": { "anyOf": [ { "type": "object", "properties": { "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run it carried out: its `id` in List an automation's runs." }, "name": { "type": "string", "description": "The automation's name when that automation run was recorded." } }, "required": [ "automationId", "automationRunId", "name" ] }, { "type": "null" } ], "description": "The automation that started this run; `null` for a run the user started with a message." }, "reads": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "account", "prices" ] }, "description": "What the agent read while it worked, told by the tools whose calls completed: `account` (the user's own balances, holdings, orders or positions) and `prices` (market prices). Empty when it read neither." } }, "required": [ "id", "conversationId", "input", "profile", "startedAt", "endedAt", "status", "output", "response", "error", "failure", "pendingApprovals", "pendingQuestions", "steers", "feedback", "origin", "reads" ], "description": "The agent's work on one message: its status, the agent's reply once it finishes, any approvals or questionnaires it is waiting on, the messages the user sent it while it worked, and the user's feedback on the reply." }, "RunOutputObjectSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "JSON Schema type keyword: object." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/RunOutputSchemaNode" }, "description": "Named fields and their strict schemas." }, "required": { "type": "array", "items": { "type": "string" }, "description": "Every declared property is required exactly once." }, "additionalProperties": { "type": "boolean", "const": false, "description": "Always false; undeclared properties are rejected." } }, "required": [ "type", "properties", "required", "additionalProperties" ], "description": "A strict object with all declared properties required and no extra properties." }, "RunOutputSchemaNode": { "description": "A bounded node in the strict JSON Schema supported for run output.", "$ref": "#/components/schemas/schema0" }, "schema0": { "anyOf": [ { "$ref": "#/components/schemas/RunOutputObjectSchema" }, { "type": "object", "properties": { "type": { "type": "string", "const": "array", "description": "JSON Schema type keyword: array." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "items": { "description": "Schema every array entry must satisfy.", "$ref": "#/components/schemas/RunOutputSchemaNode" }, "minItems": { "description": "Inclusive minimum number of array entries.", "type": "number" }, "maxItems": { "description": "Inclusive maximum number of array entries.", "type": "number" } }, "required": [ "type", "items" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "JSON Schema type keyword: string." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "string" } }, "minLength": { "description": "Inclusive minimum string length.", "type": "number" }, "maxLength": { "description": "Inclusive maximum string length.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "JSON Schema type keyword: number." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "JSON Schema type keyword: integer." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "JSON Schema type keyword: boolean." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "boolean" } } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "null", "description": "JSON Schema type keyword: null." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" } }, "required": [ "type" ] } ], "description": "One supported strict JSON Schema node: object, array, string, number, integer, boolean or null." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "RunSteer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The message's id; the `run.steered` event that delivers it names it." }, "text": { "type": "string", "description": "The message, as the user sent it." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dropped" ], "description": "`pending` until the agent reads it at its next step; `delivered` once it has; `dropped` when the run ended before the agent read it, so it was never acted on. Send a dropped message again with Start a run." }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user sent it." }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the agent read it; null until it is `delivered`." } }, "required": [ "id", "text", "status", "sentAt", "deliveredAt" ], "description": "A message the user sent a run while it was working, and whether the agent read it." }, "RunFeedback": { "type": "object", "properties": { "rating": { "$ref": "#/components/schemas/RunFeedbackRating" }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedbackReason" }, { "type": "null" } ], "description": "Why the user rated it down; null when they gave no reason or rated it `up`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user first sent feedback on this run's reply." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the feedback last changed; the same as `createdAt` until it does." } }, "required": [ "rating", "reason", "createdAt", "updatedAt" ], "description": "The user's feedback on one run's reply: a thumbs-up or thumbs-down, and why." }, "RunFeedbackRating": { "type": "string", "enum": [ "up", "down" ], "description": "How the user rated the reply: `up` for a thumbs-up, `down` for a thumbs-down." }, "RunFeedbackReason": { "type": "string", "enum": [ "wrong", "unhelpful", "slow", "unsafe", "other" ], "description": "Why the user rated the reply down: `wrong` it was incorrect, `unhelpful` it did not do what was asked, `slow` it took too long, `unsafe` it was risky or inappropriate, `other` none of these." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Cancel a run 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`. `POST /v1/users/{userId}/runs/{runId}/cancel` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/runs/YOUR_RUN_ID/cancel' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The run, stopped. ```json { "description": "The run, stopped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `run_not_active` — the run named in the path is not the conversation's live run - `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed ```json { "description": "The operation lost to the current state.\n\n- `run_not_active` — the run named in the path is not the conversation's live run\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "runs.cancel", "summary": "Cancel a run", "tags": [ "runs" ], "description": "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`.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The run, stopped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `run_not_active` — the run named in the path is not the conversation's live run\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "Run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id. It stays the same while the run pauses for approvals and resumes." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "input": { "description": "The user's message that started the run; null only for old runs that did not keep it.", "type": [ "string", "null" ] }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "Meaning of this terminal output contract.", "type": "string", "maxLength": 4096 }, "schema": { "description": "The immutable strict object schema that the terminal output must satisfy.", "$ref": "#/components/schemas/RunOutputObjectSchema" } }, "required": [ "name", "schema" ], "description": "The immutable admitted output contract, readable without invoking its admission transform." }, "modelId": { "description": "The reviewed provider model pinned by trusted admission; absent for historical default selection.", "type": "string", "minLength": 1, "maxLength": 200 } }, "description": "The tools, output contract and model the run started with. They never change." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the run started." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the run ended; null while it is running or paused for human input or approval." }, "status": { "$ref": "#/components/schemas/RunStatus" }, "output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "null" } ], "description": "The run's terminal structured result, once it has one under its `outputContract`; null otherwise." }, "response": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "description": "The agent's full reply, never shortened." }, "eventSeq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The `seq` of the event that carries the reply." }, "completeness": { "type": "string", "enum": [ "complete", "partial" ], "description": "`complete` when the run completed; `partial` when it was stopped or failed before finishing." } }, "required": [ "text", "eventSeq", "completeness" ] }, { "type": "null" } ], "description": "The agent's reply since the run last started, resumed or was steered, once it has one." }, "error": { "description": "Why the run failed or was stopped; null when neither happened.", "type": [ "string", "null" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "model_timeout", "model_invalid_output", "execution_deadline", "provider_rate_limit", "provider_unavailable", "provider_authentication", "internal_error", "context_too_large", "daily_budget_exhausted", "monthly_budget_exhausted", "budget_frozen", "partner_daily_budget_exhausted", "partner_monthly_budget_exhausted", "unknown" ], "description": "Why the execution failed: `model_timeout` (the model was too slow to respond), `execution_deadline` (the run's active time limit elapsed before it finished), `provider_rate_limit` or `provider_unavailable` (classified from HTTP status or a connection/body-read failure observed by the host), `model_invalid_output` (terminal structured output still failed its required format after bounded repair), `context_too_large` (the request stayed over the model's context window after the host condensed earlier history and retried once), `daily_budget_exhausted`, `monthly_budget_exhausted` or `budget_frozen` (the user's AI budget for the UTC day or month, or an operator's freeze on it, left no room for the run's next model request), `partner_daily_budget_exhausted` or `partner_monthly_budget_exhausted` (the partner account's AI spend limit for the UTC day or month left no room for it), `internal_error` (a host-side fault), or `unknown` when nothing more specific was classified. A budget or spend-limit code means a limit stopped the run, not that the model failed; trying again fails the same way until the limit clears. A raised user budget or a lifted freeze applies at once; a raised partner limit applies from the next UTC day or month, because the open period keeps the cap it started with." }, "stage": { "type": "string", "enum": [ "model_request", "tool_execution", "finalization" ], "description": "Which phase of the run was executing when it failed: `model_request` while calling or awaiting the model provider, `tool_execution` while running or resuming a tool call, or `finalization` while settling the run's output and accounting after the model finished." }, "providerMessage": { "description": "The model provider's own error text, when one was available: credential values are redacted and it is cut to 256 characters, but it is not a content classifier, so other sensitive detail may remain. Treat it as diagnostic context only — never branch on it, and review before showing it to an end user.", "type": "string", "minLength": 1, "maxLength": 256 }, "diagnosticReference": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This failed run's own id, repeated here as one field to cite when asking support to check the host's internal logs for this execution; it carries no meaning beyond that." }, "effectWarning": { "type": "string", "const": "Earlier actions may have completed. Partial output does not prove success or a delivery failure. Check receipts before retrying; retrying may repeat actions.", "description": "This build's fixed caution: earlier actions may already have run, so partial output alone never proves success, a delivery failure, or that retrying is free of duplicate effects." } }, "required": [ "code", "stage", "diagnosticReference", "effectWarning" ] }, { "type": "null" } ], "description": "Details of a failure, when recorded." }, "pendingApprovals": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "description": "The approvals this run is waiting on, oldest first." }, "pendingQuestions": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The questionnaire ids this run is waiting on, oldest first." }, "steers": { "type": "array", "items": { "$ref": "#/components/schemas/RunSteer" }, "description": "The messages the user sent this run while it worked, with Steer a run, oldest first; empty when they sent none." }, "feedback": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedback" }, { "type": "null" } ], "description": "The user's feedback on this run's reply; null until they send it." }, "origin": { "anyOf": [ { "type": "object", "properties": { "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run it carried out: its `id` in List an automation's runs." }, "name": { "type": "string", "description": "The automation's name when that automation run was recorded." } }, "required": [ "automationId", "automationRunId", "name" ] }, { "type": "null" } ], "description": "The automation that started this run; `null` for a run the user started with a message." }, "reads": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "account", "prices" ] }, "description": "What the agent read while it worked, told by the tools whose calls completed: `account` (the user's own balances, holdings, orders or positions) and `prices` (market prices). Empty when it read neither." } }, "required": [ "id", "conversationId", "input", "profile", "startedAt", "endedAt", "status", "output", "response", "error", "failure", "pendingApprovals", "pendingQuestions", "steers", "feedback", "origin", "reads" ], "description": "The agent's work on one message: its status, the agent's reply once it finishes, any approvals or questionnaires it is waiting on, the messages the user sent it while it worked, and the user's feedback on the reply." }, "RunOutputObjectSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "JSON Schema type keyword: object." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/RunOutputSchemaNode" }, "description": "Named fields and their strict schemas." }, "required": { "type": "array", "items": { "type": "string" }, "description": "Every declared property is required exactly once." }, "additionalProperties": { "type": "boolean", "const": false, "description": "Always false; undeclared properties are rejected." } }, "required": [ "type", "properties", "required", "additionalProperties" ], "description": "A strict object with all declared properties required and no extra properties." }, "RunOutputSchemaNode": { "description": "A bounded node in the strict JSON Schema supported for run output.", "$ref": "#/components/schemas/schema0" }, "schema0": { "anyOf": [ { "$ref": "#/components/schemas/RunOutputObjectSchema" }, { "type": "object", "properties": { "type": { "type": "string", "const": "array", "description": "JSON Schema type keyword: array." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "items": { "description": "Schema every array entry must satisfy.", "$ref": "#/components/schemas/RunOutputSchemaNode" }, "minItems": { "description": "Inclusive minimum number of array entries.", "type": "number" }, "maxItems": { "description": "Inclusive maximum number of array entries.", "type": "number" } }, "required": [ "type", "items" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "JSON Schema type keyword: string." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "string" } }, "minLength": { "description": "Inclusive minimum string length.", "type": "number" }, "maxLength": { "description": "Inclusive maximum string length.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "JSON Schema type keyword: number." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "JSON Schema type keyword: integer." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "JSON Schema type keyword: boolean." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "boolean" } } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "null", "description": "JSON Schema type keyword: null." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" } }, "required": [ "type" ] } ], "description": "One supported strict JSON Schema node: object, array, string, number, integer, boolean or null." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "RunSteer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The message's id; the `run.steered` event that delivers it names it." }, "text": { "type": "string", "description": "The message, as the user sent it." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dropped" ], "description": "`pending` until the agent reads it at its next step; `delivered` once it has; `dropped` when the run ended before the agent read it, so it was never acted on. Send a dropped message again with Start a run." }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user sent it." }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the agent read it; null until it is `delivered`." } }, "required": [ "id", "text", "status", "sentAt", "deliveredAt" ], "description": "A message the user sent a run while it was working, and whether the agent read it." }, "RunFeedback": { "type": "object", "properties": { "rating": { "$ref": "#/components/schemas/RunFeedbackRating" }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedbackReason" }, { "type": "null" } ], "description": "Why the user rated it down; null when they gave no reason or rated it `up`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user first sent feedback on this run's reply." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the feedback last changed; the same as `createdAt` until it does." } }, "required": [ "rating", "reason", "createdAt", "updatedAt" ], "description": "The user's feedback on one run's reply: a thumbs-up or thumbs-down, and why." }, "RunFeedbackRating": { "type": "string", "enum": [ "up", "down" ], "description": "How the user rated the reply: `up` for a thumbs-up, `down` for a thumbs-down." }, "RunFeedbackReason": { "type": "string", "enum": [ "wrong", "unhelpful", "slow", "unsafe", "other" ], "description": "Why the user rated the reply down: `wrong` it was incorrect, `unhelpful` it did not do what was asked, `slow` it took too long, `unsafe` it was risky or inappropriate, `other` none of these." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Send run feedback 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`. `PUT /v1/users/{userId}/runs/{runId}/feedback` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "$ref": "#/components/schemas/RunFeedbackRatingInput" }, "reason": { "$ref": "#/components/schemas/RunFeedbackReasonInput" } }, "required": [ "rating" ], "additionalProperties": false }, "example": { "rating": "down", "reason": "wrong" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request PUT 'https://api.example.test/v1/users/YOUR_USER_ID/runs/YOUR_RUN_ID/feedback' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "rating": "down", "reason": "wrong" }' ``` ## Responses ### 200 The feedback as it now stands. ```json { "description": "The feedback as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFeedback" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `run_active` — a run already holds this conversation ```json { "description": "The operation lost to the current state.\n\n- `run_active` — a run already holds this conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "runs.sendFeedback", "summary": "Send run feedback", "tags": [ "runs" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "$ref": "#/components/schemas/RunFeedbackRatingInput" }, "reason": { "$ref": "#/components/schemas/RunFeedbackReasonInput" } }, "required": [ "rating" ], "additionalProperties": false }, "example": { "rating": "down", "reason": "wrong" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The feedback as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFeedback" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `run_active` — a run already holds this conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "RunFeedbackRatingInput": { "type": "string", "enum": [ "up", "down" ], "description": "How the user rated the reply: `up` for a thumbs-up, `down` for a thumbs-down." }, "RunFeedbackReasonInput": { "type": "string", "enum": [ "wrong", "unhelpful", "slow", "unsafe", "other" ], "description": "Why the user rated the reply down: `wrong` it was incorrect, `unhelpful` it did not do what was asked, `slow` it took too long, `unsafe` it was risky or inappropriate, `other` none of these." }, "RunFeedback": { "type": "object", "properties": { "rating": { "$ref": "#/components/schemas/RunFeedbackRating" }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedbackReason" }, { "type": "null" } ], "description": "Why the user rated it down; null when they gave no reason or rated it `up`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user first sent feedback on this run's reply." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the feedback last changed; the same as `createdAt` until it does." } }, "required": [ "rating", "reason", "createdAt", "updatedAt" ], "description": "The user's feedback on one run's reply: a thumbs-up or thumbs-down, and why." }, "RunFeedbackRating": { "type": "string", "enum": [ "up", "down" ], "description": "How the user rated the reply: `up` for a thumbs-up, `down` for a thumbs-down." }, "RunFeedbackReason": { "type": "string", "enum": [ "wrong", "unhelpful", "slow", "unsafe", "other" ], "description": "Why the user rated the reply down: `wrong` it was incorrect, `unhelpful` it did not do what was asked, `slow` it took too long, `unsafe` it was risky or inappropriate, `other` none of these." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Delete run feedback 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. `DELETE /v1/users/{userId}/runs/{runId}/feedback` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request DELETE 'https://api.example.test/v1/users/YOUR_USER_ID/runs/YOUR_RUN_ID/feedback' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 204 The feedback is deleted. ```json { "description": "The feedback is deleted." } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "runs.deleteFeedback", "summary": "Delete run feedback", "tags": [ "runs" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "runId", "required": true, "description": "The run's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "204": { "description": "The feedback is deleted." }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get voice input 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. `GET /v1/users/{userId}/voice` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/voice' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 Whether the user can send recordings now. ```json { "description": "Whether the user can send recordings now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voice" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "voice.get", "summary": "Get voice input", "tags": [ "voice" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "Whether the user can send recordings now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voice" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Voice": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "disabled", "unavailable" ], "description": "`available`: the user can send recordings now. `disabled`: voice input is not turned on for this user. `unavailable`: this deployment has no speech model. Show a microphone only while it is `available`." }, "maxSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The longest recording to send, in seconds. Stop recording when it is reached." }, "formats": { "type": "array", "items": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "audio/webm", "audio/mp4", "audio/ogg", "audio/wav" ], "description": "The audio type, as the `Content-Type` header names it. Codec parameters are allowed (`audio/ogg;codecs=opus`)." }, "maxBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The largest recording of this type Fin accepts, in bytes: a minute of speech with room to spare. A larger one answers `413`." } }, "required": [ "contentType", "maxBytes" ] }, "description": "The audio a recording may be sent as: the types this deployment's speech model decodes, each with its largest size. Send one of these. A browser that records another (the WebM Chrome, Edge and Safari record) converts its recording to WAV first. Empty when there is no speech model." } }, "required": [ "status", "maxSeconds", "formats" ], "description": "Whether the user can talk instead of type, and the limits a recording must keep to." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Transcribe a recording 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. `POST /v1/users/{userId}/voice/transcriptions` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "audio/webm": { "schema": { "type": "string", "format": "binary", "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." } }, "audio/mp4": { "schema": { "type": "string", "format": "binary", "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." } }, "audio/ogg": { "schema": { "type": "string", "format": "binary", "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." } }, "audio/wav": { "schema": { "type": "string", "format": "binary", "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." } } }, "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/voice/transcriptions' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: audio/webm' \ --data-binary '@request.json' ``` ## Responses ### 200 The recording's words. ```json { "description": "The recording's words.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcription" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `voice_disabled` — voice input is not turned on for this user; let them type instead ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `voice_disabled` — voice input is not turned on for this user; let them type instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `voice_unavailable` — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `voice_unavailable` — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "voice.transcribe", "summary": "Transcribe a recording", "tags": [ "voice" ], "description": "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.", "requestBody": { "required": true, "content": { "audio/webm": { "schema": { "type": "string", "format": "binary", "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." } }, "audio/mp4": { "schema": { "type": "string", "format": "binary", "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." } }, "audio/ogg": { "schema": { "type": "string", "format": "binary", "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." } }, "audio/wav": { "schema": { "type": "string", "format": "binary", "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." } } }, "description": "The recording's bytes, in one of the formats Get voice input lists, named by `Content-Type` and at most that format's `maxBytes`." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The recording's words.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcription" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `voice_disabled` — voice input is not turned on for this user; let them type instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `voice_unavailable` — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "Transcription": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 8192, "description": "What the recording says, as text. Empty when no speech was heard: say so and let the user try again." } }, "required": [ "text" ], "description": "The words of one recording. Nothing is sent to the agent: put them where the user writes, to read, change and send." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a question 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. `GET /v1/users/{userId}/questions/{questionId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "questionId", "required": true, "description": "The questionnaire's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/questions/YOUR_QUESTION_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The questionnaire and its current answer, if one was accepted. ```json { "description": "The questionnaire and its current answer, if one was accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The questionnaire's unique id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation containing this questionnaire." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run waiting for this questionnaire." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call that opened this questionnaire." }, "questions": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The stable id used to match this question with its answer." }, "label": { "description": "Optional short title for this question.", "type": "string", "minLength": 1, "maxLength": 128 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The question text shown to the user." }, "options": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The stable value returned when this option is selected." }, "label": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The text shown to the user for this option." }, "description": { "description": "Optional explanation shown with this option.", "type": "string", "maxLength": 512 }, "recommended": { "description": "Whether this is the option the agent recommends: at most one per question, with why in its description.", "type": "boolean" }, "picture": { "description": "A small drawing an app may show over this choice: `schedule` for buying on a regular schedule, `dip` for buying only after a fall, `once` for one buy now. Absent when none fits; an app that draws none shows the choice without it.", "type": "string", "enum": [ "schedule", "dip", "once" ] } }, "required": [ "value", "label" ], "description": "One choice presented for a question." }, "description": "The choices shown for this question." }, "multiple": { "description": "Whether the user may select more than one choice.", "type": "boolean" }, "amount": { "type": "object", "properties": { "min": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The smallest amount the slider offers, as a decimal string." }, "max": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The largest amount the slider offers, as a decimal string." }, "step": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "How far one slider step moves, as a decimal string." }, "unit": { "type": "string", "minLength": 1, "maxLength": 16, "description": "What the amount counts: \"usd\" for dollars, or a token symbol such as \"USDC\"." } }, "required": [ "min", "max", "step", "unit" ], "description": "Asks for one amount on a slider. The options are its presets, each value a decimal string within min and max; an amount between them is answered as customText." } }, "required": [ "id", "prompt", "options" ], "description": "One question and its available choices." }, "description": "The questions and choices shown to the user." }, "status": { "type": "string", "enum": [ "pending", "answered", "skipped", "expired", "cancelled" ], "description": "The current questionnaire status." }, "answer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "description": "The questionnaire was answered.", "enum": [ "answered" ] }, "answers": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The id of the question this answer corresponds to." }, "values": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Selected option values; empty when customText is supplied." }, "customText": { "description": "Optional user-supplied text in place of selected options.", "type": "string", "maxLength": 2048 } }, "required": [ "id", "values" ], "description": "The user's answer to one question." }, "description": "The selected options or custom text for each question the user answered. A question they skipped has no answer." } }, "required": [ "status", "answers" ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "The questionnaire was skipped.", "enum": [ "skipped" ] } }, "required": [ "status" ] } ], "description": "The result of answering or skipping a questionnaire." }, { "type": "null" } ], "description": "The accepted answers or skip result, or null when none was accepted." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire was created." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire expires if unanswered." }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the questionnaire was answered, skipped, expired, or cancelled; null while pending." } }, "required": [ "id", "conversationId", "runId", "callId", "questions", "status", "answer", "createdAt", "expiresAt", "resolvedAt" ], "description": "The questionnaire resource and its current status." } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "questions.get", "summary": "Get a question", "tags": [ "questions" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "questionId", "required": true, "description": "The questionnaire's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The questionnaire and its current answer, if one was accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The questionnaire's unique id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation containing this questionnaire." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run waiting for this questionnaire." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call that opened this questionnaire." }, "questions": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The stable id used to match this question with its answer." }, "label": { "description": "Optional short title for this question.", "type": "string", "minLength": 1, "maxLength": 128 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The question text shown to the user." }, "options": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The stable value returned when this option is selected." }, "label": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The text shown to the user for this option." }, "description": { "description": "Optional explanation shown with this option.", "type": "string", "maxLength": 512 }, "recommended": { "description": "Whether this is the option the agent recommends: at most one per question, with why in its description.", "type": "boolean" }, "picture": { "description": "A small drawing an app may show over this choice: `schedule` for buying on a regular schedule, `dip` for buying only after a fall, `once` for one buy now. Absent when none fits; an app that draws none shows the choice without it.", "type": "string", "enum": [ "schedule", "dip", "once" ] } }, "required": [ "value", "label" ], "description": "One choice presented for a question." }, "description": "The choices shown for this question." }, "multiple": { "description": "Whether the user may select more than one choice.", "type": "boolean" }, "amount": { "type": "object", "properties": { "min": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The smallest amount the slider offers, as a decimal string." }, "max": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The largest amount the slider offers, as a decimal string." }, "step": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "How far one slider step moves, as a decimal string." }, "unit": { "type": "string", "minLength": 1, "maxLength": 16, "description": "What the amount counts: \"usd\" for dollars, or a token symbol such as \"USDC\"." } }, "required": [ "min", "max", "step", "unit" ], "description": "Asks for one amount on a slider. The options are its presets, each value a decimal string within min and max; an amount between them is answered as customText." } }, "required": [ "id", "prompt", "options" ], "description": "One question and its available choices." }, "description": "The questions and choices shown to the user." }, "status": { "type": "string", "enum": [ "pending", "answered", "skipped", "expired", "cancelled" ], "description": "The current questionnaire status." }, "answer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "description": "The questionnaire was answered.", "enum": [ "answered" ] }, "answers": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The id of the question this answer corresponds to." }, "values": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Selected option values; empty when customText is supplied." }, "customText": { "description": "Optional user-supplied text in place of selected options.", "type": "string", "maxLength": 2048 } }, "required": [ "id", "values" ], "description": "The user's answer to one question." }, "description": "The selected options or custom text for each question the user answered. A question they skipped has no answer." } }, "required": [ "status", "answers" ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "The questionnaire was skipped.", "enum": [ "skipped" ] } }, "required": [ "status" ] } ], "description": "The result of answering or skipping a questionnaire." }, { "type": "null" } ], "description": "The accepted answers or skip result, or null when none was accepted." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire was created." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire expires if unanswered." }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the questionnaire was answered, skipped, expired, or cancelled; null while pending." } }, "required": [ "id", "conversationId", "runId", "callId", "questions", "status", "answer", "createdAt", "expiresAt", "resolvedAt" ], "description": "The questionnaire resource and its current status." } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Answer a question 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`. `POST /v1/users/{userId}/questions/{questionId}/answer` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "questionId", "required": true, "description": "The questionnaire's id." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Submit the user's answers.", "enum": [ "answers" ] }, "answers": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The id of the question this answer corresponds to." }, "values": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Selected option values; empty when customText is supplied." }, "customText": { "description": "Optional user-supplied text in place of selected options.", "type": "string", "maxLength": 2048 } }, "required": [ "id", "values" ], "additionalProperties": false, "description": "The user's answer to one question." }, "description": "The user's answer to each question they answered. Leave out a question they skipped." } }, "required": [ "kind", "answers" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Skip the entire questionnaire.", "enum": [ "skip" ] } }, "required": [ "kind" ], "additionalProperties": false } ], "description": "Answers to the questionnaire or a request to skip it." } } }, "description": "Answers to the questionnaire or a request to skip it." } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/questions/YOUR_QUESTION_ID/answer' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The questionnaire after its answer was accepted. ```json { "description": "The questionnaire after its answer was accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The questionnaire's unique id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation containing this questionnaire." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run waiting for this questionnaire." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call that opened this questionnaire." }, "questions": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The stable id used to match this question with its answer." }, "label": { "description": "Optional short title for this question.", "type": "string", "minLength": 1, "maxLength": 128 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The question text shown to the user." }, "options": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The stable value returned when this option is selected." }, "label": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The text shown to the user for this option." }, "description": { "description": "Optional explanation shown with this option.", "type": "string", "maxLength": 512 }, "recommended": { "description": "Whether this is the option the agent recommends: at most one per question, with why in its description.", "type": "boolean" }, "picture": { "description": "A small drawing an app may show over this choice: `schedule` for buying on a regular schedule, `dip` for buying only after a fall, `once` for one buy now. Absent when none fits; an app that draws none shows the choice without it.", "type": "string", "enum": [ "schedule", "dip", "once" ] } }, "required": [ "value", "label" ], "description": "One choice presented for a question." }, "description": "The choices shown for this question." }, "multiple": { "description": "Whether the user may select more than one choice.", "type": "boolean" }, "amount": { "type": "object", "properties": { "min": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The smallest amount the slider offers, as a decimal string." }, "max": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The largest amount the slider offers, as a decimal string." }, "step": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "How far one slider step moves, as a decimal string." }, "unit": { "type": "string", "minLength": 1, "maxLength": 16, "description": "What the amount counts: \"usd\" for dollars, or a token symbol such as \"USDC\"." } }, "required": [ "min", "max", "step", "unit" ], "description": "Asks for one amount on a slider. The options are its presets, each value a decimal string within min and max; an amount between them is answered as customText." } }, "required": [ "id", "prompt", "options" ], "description": "One question and its available choices." }, "description": "The questions and choices shown to the user." }, "status": { "type": "string", "enum": [ "pending", "answered", "skipped", "expired", "cancelled" ], "description": "The current questionnaire status." }, "answer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "description": "The questionnaire was answered.", "enum": [ "answered" ] }, "answers": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The id of the question this answer corresponds to." }, "values": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Selected option values; empty when customText is supplied." }, "customText": { "description": "Optional user-supplied text in place of selected options.", "type": "string", "maxLength": 2048 } }, "required": [ "id", "values" ], "description": "The user's answer to one question." }, "description": "The selected options or custom text for each question the user answered. A question they skipped has no answer." } }, "required": [ "status", "answers" ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "The questionnaire was skipped.", "enum": [ "skipped" ] } }, "required": [ "status" ] } ], "description": "The result of answering or skipping a questionnaire." }, { "type": "null" } ], "description": "The accepted answers or skip result, or null when none was accepted." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire was created." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire expires if unanswered." }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the questionnaire was answered, skipped, expired, or cancelled; null while pending." } }, "required": [ "id", "conversationId", "runId", "callId", "questions", "status", "answer", "createdAt", "expiresAt", "resolvedAt" ], "description": "The questionnaire resource and its current status." } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted - `invalid_question_answer` — the questionnaire answer does not match its questions or allowed choices ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `invalid_question_answer` — the questionnaire answer does not match its questions or allowed choices", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request - `question_not_pending` — the questionnaire has already been answered, closed, or is not awaiting this submission - `run_active` — a run already holds this conversation ```json { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `run_active` — a run already holds this conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 410 The resource still exists and stays readable, but can no longer take this request. - `question_closed` — the questionnaire expired or was cancelled ```json { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `question_closed` — the questionnaire expired or was cancelled", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `execution_capacity` — no capacity is free to run this right now; honour `Retry-After` - `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "questions.answer", "summary": "Answer a question", "tags": [ "questions" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Submit the user's answers.", "enum": [ "answers" ] }, "answers": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The id of the question this answer corresponds to." }, "values": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Selected option values; empty when customText is supplied." }, "customText": { "description": "Optional user-supplied text in place of selected options.", "type": "string", "maxLength": 2048 } }, "required": [ "id", "values" ], "additionalProperties": false, "description": "The user's answer to one question." }, "description": "The user's answer to each question they answered. Leave out a question they skipped." } }, "required": [ "kind", "answers" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Skip the entire questionnaire.", "enum": [ "skip" ] } }, "required": [ "kind" ], "additionalProperties": false } ], "description": "Answers to the questionnaire or a request to skip it." } } }, "description": "Answers to the questionnaire or a request to skip it." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "questionId", "required": true, "description": "The questionnaire's id." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The questionnaire after its answer was accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The questionnaire's unique id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation containing this questionnaire." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run waiting for this questionnaire." }, "callId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The tool call that opened this questionnaire." }, "questions": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The stable id used to match this question with its answer." }, "label": { "description": "Optional short title for this question.", "type": "string", "minLength": 1, "maxLength": 128 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The question text shown to the user." }, "options": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The stable value returned when this option is selected." }, "label": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The text shown to the user for this option." }, "description": { "description": "Optional explanation shown with this option.", "type": "string", "maxLength": 512 }, "recommended": { "description": "Whether this is the option the agent recommends: at most one per question, with why in its description.", "type": "boolean" }, "picture": { "description": "A small drawing an app may show over this choice: `schedule` for buying on a regular schedule, `dip` for buying only after a fall, `once` for one buy now. Absent when none fits; an app that draws none shows the choice without it.", "type": "string", "enum": [ "schedule", "dip", "once" ] } }, "required": [ "value", "label" ], "description": "One choice presented for a question." }, "description": "The choices shown for this question." }, "multiple": { "description": "Whether the user may select more than one choice.", "type": "boolean" }, "amount": { "type": "object", "properties": { "min": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The smallest amount the slider offers, as a decimal string." }, "max": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "The largest amount the slider offers, as a decimal string." }, "step": { "type": "string", "maxLength": 40, "pattern": "^(0|[1-9]\\d{0,20})(\\.\\d{1,18})?$", "description": "How far one slider step moves, as a decimal string." }, "unit": { "type": "string", "minLength": 1, "maxLength": 16, "description": "What the amount counts: \"usd\" for dollars, or a token symbol such as \"USDC\"." } }, "required": [ "min", "max", "step", "unit" ], "description": "Asks for one amount on a slider. The options are its presets, each value a decimal string within min and max; an amount between them is answered as customText." } }, "required": [ "id", "prompt", "options" ], "description": "One question and its available choices." }, "description": "The questions and choices shown to the user." }, "status": { "type": "string", "enum": [ "pending", "answered", "skipped", "expired", "cancelled" ], "description": "The current questionnaire status." }, "answer": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "description": "The questionnaire was answered.", "enum": [ "answered" ] }, "answers": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The id of the question this answer corresponds to." }, "values": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Selected option values; empty when customText is supplied." }, "customText": { "description": "Optional user-supplied text in place of selected options.", "type": "string", "maxLength": 2048 } }, "required": [ "id", "values" ], "description": "The user's answer to one question." }, "description": "The selected options or custom text for each question the user answered. A question they skipped has no answer." } }, "required": [ "status", "answers" ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "The questionnaire was skipped.", "enum": [ "skipped" ] } }, "required": [ "status" ] } ], "description": "The result of answering or skipping a questionnaire." }, { "type": "null" } ], "description": "The accepted answers or skip result, or null when none was accepted." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire was created." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the questionnaire expires if unanswered." }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the questionnaire was answered, skipped, expired, or cancelled; null while pending." } }, "required": [ "id", "conversationId", "runId", "callId", "questions", "status", "answer", "createdAt", "expiresAt", "resolvedAt" ], "description": "The questionnaire resource and its current status." } } } }, "400": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `invalid_question_answer` — the questionnaire answer does not match its questions or allowed choices", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `run_active` — a run already holds this conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "410": { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `question_closed` — the questionnaire expired or was cancelled", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List approvals 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 /v1/users/{userId}/approvals` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "default": "pending", "type": "string", "enum": [ "pending", "approved", "denied", "expired", "all" ] }, "in": "query", "name": "status", "required": false, "description": "Which approvals to list: `pending` (the default: the only ones you can decide), `approved`, `denied`, `expired`, or `all`." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "conversationId", "required": false, "description": "Only the approvals asked for in this conversation; omit for all of the user's." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/approvals' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of the user's approvals. ```json { "description": "A page of the user's approvals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "approvals.list", "summary": "List approvals", "tags": [ "approvals" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "default": "pending", "type": "string", "enum": [ "pending", "approved", "denied", "expired", "all" ] }, "in": "query", "name": "status", "required": false, "description": "Which approvals to list: `pending` (the default: the only ones you can decide), `approved`, `denied`, `expired`, or `all`." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "conversationId", "required": false, "description": "Only the approvals asked for in this conversation; omit for all of the user's." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of the user's approvals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "tool": { "type": "string", "description": "The tool the agent wants to use." }, "fingerprint": { "type": "string", "description": "The SHA-256 digest, as 64 lowercase hexadecimal characters, of the tool and its exact input in canonical JSON, with the deployment's no-signing restriction when it set one: the decision applies to exactly this action, and the action that runs must match it." }, "input": { "description": "The tool's input, exactly as it would run: show it to the user.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, { "type": "null" } ], "description": "For a money action, the amounts, assets, destinations and limits approving it allows; `null` for other actions." }, "authorization": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalAuthorization" }, { "type": "null" } ], "description": "For a money action waiting for a decision: the message the user signs to approve it, and the request it covers. `null` for other actions, once decided, and for withdrawals the user starts with Withdraw funds, which approves them itself." }, "summary": { "type": "string", "description": "A short summary of what approving would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "`pending` while it waits for a decision, `approved` or `denied` once decided, or `expired` when nobody decided before `expiresAt`." }, "reason": { "description": "Why it was decided, if a reason was given.", "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the agent asked." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval expires if nobody decides it." }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the approved action started, or `null` until then (always `null` when denied). The action can still fail afterwards: this is not proof it succeeded." }, "signedBy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192 }, { "type": "null" } ], "description": "For an approved money action, which only the user's signature approves: the sign-in wallet that signed it, by its public identifier (an EVM, Solana, Stellar or Tron address, a NEAR account, a TON public key, or a passkey's credential id). A user's sign-in wallet is fixed at their first sign-in and never replaced, so reading it now names the same wallet that signed when the action was approved. `null` for any other approval, and for a money action approved before the user's sign-in wallet was registered, when approvals took no signature." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The run waiting on this approval; `null` only for old approvals." }, "operationId": { "type": "null", "description": "Always `null` for an approval a run is waiting on." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "authorization", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "signedBy", "conversationId", "runId", "operationId" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "tool": { "type": "string", "description": "The tool the agent wants to use." }, "fingerprint": { "type": "string", "description": "The SHA-256 digest, as 64 lowercase hexadecimal characters, of the tool and its exact input in canonical JSON, with the deployment's no-signing restriction when it set one: the decision applies to exactly this action, and the action that runs must match it." }, "input": { "description": "The tool's input, exactly as it would run: show it to the user.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, { "type": "null" } ], "description": "For a money action, the amounts, assets, destinations and limits approving it allows; `null` for other actions." }, "authorization": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalAuthorization" }, { "type": "null" } ], "description": "For a money action waiting for a decision: the message the user signs to approve it, and the request it covers. `null` for other actions, once decided, and for withdrawals the user starts with Withdraw funds, which approves them itself." }, "summary": { "type": "string", "description": "A short summary of what approving would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "`pending` while it waits for a decision, `approved` or `denied` once decided, or `expired` when nobody decided before `expiresAt`." }, "reason": { "description": "Why it was decided, if a reason was given.", "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the agent asked." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval expires if nobody decides it." }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the approved action started, or `null` until then (always `null` when denied). The action can still fail afterwards: this is not proof it succeeded." }, "signedBy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192 }, { "type": "null" } ], "description": "For an approved money action, which only the user's signature approves: the sign-in wallet that signed it, by its public identifier (an EVM, Solana, Stellar or Tron address, a NEAR account, a TON public key, or a passkey's credential id). A user's sign-in wallet is fixed at their first sign-in and never replaced, so reading it now names the same wallet that signed when the action was approved. `null` for any other approval, and for a money action approved before the user's sign-in wallet was registered, when approvals took no signature." }, "conversationId": { "type": "null", "description": "Always `null`: a withdrawal's review belongs to the withdrawal." }, "runId": { "type": "null", "description": "Always `null`: a withdrawal has no run." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal this review belongs to (its `id` in Get a withdrawal). Withdraw funds decides it." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "authorization", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "signedBy", "conversationId", "runId", "operationId" ] } ], "description": "An action the agent wants to take that needs the user's OK: what it would do, and whether the user decided." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "LimitOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "limit_order", "description": "Which contract template this is." }, "order": { "type": "object", "properties": { "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order sells: token id and decimals." } }, "required": [ "pinned" ], "description": "The input (base) asset this order sells." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order buys: token id and decimals." } }, "required": [ "pinned" ], "description": "The output (quote) asset this order buys." }, "quantity": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount to sell, in the input asset's smallest unit. 1 NEAR with verified decimals 24 is \"1000000000000000000000000\". Scale decimal digits with the verified decimals and reject excess fractional digits; no floating-point arithmetic or bash." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The minimum price the fill must reach, as output-asset units per ONE input unit, written as a plain human decimal: \"5\" means at least 5 output tokens per 1 input token. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order may rest before it expires, in whole hours. Use the user's duration within this wallet's maximum, or the wallet's default from the latest request's host context when none is given. The schema permits up to 720 hours (30 days); a wallet may have a lower maximum. Never shorten a requested duration to fit." } }, "required": [ "input", "output", "quantity", "limitPrice", "expiresInHours" ], "description": "The exact approved placement request." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest instant the order may be created and funded under this consent." } }, "required": [ "type", "order", "validUntil" ], "description": "Owner-signed authority for one resting limit order: the exact approved placement, created and funded once by the policy worker before the approval expires." }, "PerpsTransferContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_transfer", "description": "Which authorization contract this is." }, "direction": { "type": "string", "enum": [ "fund", "withdraw" ], "description": "Fund the own perps account from the agent wallet, or withdraw back to the same agent wallet." }, "transfer": { "description": "The exact approved amount and all-in loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PerpsTransferInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "direction", "transfer", "validUntil" ], "description": "One approved perps transfer in exactly the named direction." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "PerpsOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_order", "description": "Which authorization contract this is." }, "order": { "description": "The exact approved order.", "$ref": "#/components/schemas/PerpsOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "order", "validUntil" ], "description": "One approved Hyperliquid order, signed once exactly as approved." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsCancelContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_cancel", "description": "Which authorization contract this is." }, "cancel": { "description": "The exact order approved for cancelling.", "$ref": "#/components/schemas/PerpsCancelInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "cancel", "validUntil" ], "description": "One approved cancellation of one resting Hyperliquid order." }, "PerpsCancelInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "oid": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The resting order's id exactly as perps_orders lists it." } }, "required": [ "coin", "asset", "oid" ], "description": "Cancel one resting order on the agent's own account." }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PerpsMarginContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_margin", "description": "Which authorization contract this is." }, "margin": { "description": "The exact approved margin change.", "$ref": "#/components/schemas/PerpsMarginInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "margin", "validUntil" ], "description": "One approved change to one isolated position's margin, signed once exactly as approved." }, "PerpsMarginInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "change": { "type": "string", "enum": [ "add", "remove" ], "description": "`add` moves USDC from the account into the position's isolated margin, lowering its liquidation risk; `remove` takes it back out, raising that risk. A strict isolated market never lets margin be removed while the position is open." }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,8})(\\.[0-9]{0,5}[1-9])?$", "description": "Exact USDC to move, at most six decimal places, such as `25` or `12.5`." } }, "required": [ "coin", "asset", "change", "amount" ], "description": "Add or remove margin on one isolated position on the agent's own account." }, "PredictionFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_fund", "description": "One approved Polymarket funding transfer." }, "transfer": { "description": "The exact approved USDC or USDT debit and the first leg's loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PredictionFundInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "transfer", "validUntil" ], "description": "One exact USDC or USDT debit delivered as native Base USDC to Polymarket's bridge for the agent's own account; the final pUSD amount is not bounded." }, "PredictionFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact debit in six-decimal atomic units: 5 USDC or USDT is \"5000000\", spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it. The host resolves the agent’s own Polymarket Deposit Wallet and its bridge address; never supply an address." }, "maxFirstLegLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum loss, in basis points, of the first leg only: the wallet's USDC, USDT or coin delivered as native Base USDC to Polymarket's bridge, fees and any cross-chain hop included. It does not bound the bridge's conversion to pUSD on Polygon, whose fees and output are variable and estimated. Required; no default." }, "payWith": { "description": "Approved in chat as one call or as a funded order's funding: the coin the first leg pays with instead of a USDC or USDT holding, and the most of it it may spend.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxFirstLegLossBps" ], "description": "Fund the agent's own Polymarket Deposit Wallet: one exact USDC or USDT debit, or that many dollars of a coin, delivered as native Base USDC to Polymarket's bridge, which credits an estimated, not guaranteed, pUSD amount on Polygon later." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "SolanaFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_fund", "description": "Which authorization contract this is." }, "fund": { "description": "The exact approved amount and loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaFundInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "fund", "maxExecutions", "validUntil" ], "description": "An approved move of USDC or USDT, or a coin, into the agent's own Solana account." }, "SolanaFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to move from the agent wallet into the agent's Solana account as SOL, in six-decimal atomic units: 5 USDC is \"5000000\". Spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." }, "payWith": { "description": "Approved in chat as one call: the coin this funding pays with instead of a USDC or USDT holding, and the most of it it may spend. Never SOL.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "Move an exact amount of USDC or USDT, or that many dollars of a coin, from the agent wallet into its own Solana account as SOL." }, "SolanaWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_withdraw", "description": "Which authorization contract this is." }, "withdraw": { "description": "The exact approved amount, what returns and the loss bound.", "$ref": "#/components/schemas/SolanaWithdrawInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "withdraw", "maxExecutions", "validUntil" ], "description": "An approved move of SOL from the agent's own Solana account back to its agent wallet." }, "SolanaWithdrawInput": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Withdraw an exact amount of SOL." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to withdraw, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Withdraw an exact amount of SOL." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_spendable", "description": "Withdraw all the SOL above the reserve the account keeps for rent and network fees." } }, "required": [ "kind" ], "description": "Withdraw all the spendable SOL." } ], "description": "How much SOL to withdraw from the agent's Solana account." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns it to the agent wallet as USDC on NEAR; `sol` returns it to the agent wallet as SOL." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." } }, "required": [ "amount", "receive", "maxValueLossBps" ], "description": "Move SOL from the agent's own Solana account back to its agent wallet." }, "PredictionOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_order" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "order", "validUntil" ] }, "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "PredictionWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_withdraw" }, "withdrawal": { "$ref": "#/components/schemas/PredictionWithdrawInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ] }, "PredictionWithdrawInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact pUSD debit in six-decimal atomic units: 5 pUSD is \"5000000\". Only the agent’s own Deposit Wallet is spent." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "amountRaw", "maxLossBps" ], "description": "Withdraw pUSD through Polymarket’s conversion service as native USDC on Polygon to a unique verified 1Click address crediting only the agent’s own confidential Intents wallet. Funding remains a separate USDC route." }, "CompositeContract": { "type": "object", "properties": { "type": { "type": "string", "const": "composite", "description": "Which authorization contract this is." }, "pieces": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "intents_execute", "perps_fund", "perps_order_place", "prediction_fund", "prediction_order_place", "perps_withdraw", "prediction_withdraw" ], "description": "The tool whose one-shot call this piece is." }, "contract": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, "startBy": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "tool", "contract", "startBy" ] } }, "dependencies": { "type": "array", "items": { "maxItems": 6, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "walletDebit": { "anyOf": [ { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, { "type": "array", "prefixItems": [], "items": false, "maxItems": 0 } ], "description": "The sum of every piece's debit from the agent wallet, per token, in raw units. Empty when the pieces are venue orders paid from money already on their venues, as when finishing a basket, or a cash-out, which closes a position and brings home what that freed." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When every piece that has not started loses its authority." } }, "required": [ "type", "pieces", "dependencies", "walletDebit", "validUntil" ], "description": "One owner signature over several exact one-shot grants and the order they run in." }, "PerpsFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_freed_withdrawal", "description": "Which authorization contract this is." }, "withdrawal": { "description": "The signed maximum and all-in loss bound of the withdrawal home.", "$ref": "#/components/schemas/PerpsFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's exit freed on Hyperliquid, at most the signed maximum. Only ever a piece of a cash-out." }, "PerpsFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic USDC: what the exit before it frees, sized by the host before the approval opens. Never more than the exit freed." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." } }, "required": [ "upToRaw", "maxValueLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the exit before it freed on its own Hyperliquid account, never more than upToRaw." }, "PredictionFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_freed_withdrawal" }, "withdrawal": { "$ref": "#/components/schemas/PredictionFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's sale freed on Polymarket, at most the signed maximum. Only ever a piece of a cash-out." }, "PredictionFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic pUSD: what the sale before it frees, sized by the host before the approval opens. Never more than the sale freed." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "upToRaw", "maxLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the sale before it freed in its own Polymarket Deposit Wallet, never more than upToRaw." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaSellManyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell_many", "description": "Which authorization contract this is." }, "sellMany": { "description": "The exact approved coins, amounts and loss bounds, in order, and where the proceeds go.", "$ref": "#/components/schemas/SolanaSellManyInput" }, "maxExecutions": { "type": "number", "const": 1, "description": "A multi-coin sale is approved once and runs once: always 1." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sellMany", "maxExecutions", "validUntil" ], "description": "An approved multi-coin Solana sale, executed only exactly as approved." }, "SolanaSellManyInput": { "type": "object", "properties": { "sells": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/SolanaSale" }, "description": "The coins to sell, in the order they are sold: 2 to 6, each a different mint, none of them SOL itself." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the summed proceeds of every sale that went through to the agent wallet as USDC on NEAR, in one transfer once the last sale ran; `sol` keeps them as SOL in the agent's Solana account." } }, "required": [ "sells", "receive" ], "description": "Several sells of Solana tokens held in the agent's own Solana account, approved together and run as one: each sale on its own, one after another, then one transfer of what they returned." }, "SolanaSale": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "maxValueLossBps" ], "description": "One coin of a multi-coin sale, sold through the agent's own Solana account." }, "GridContract": { "type": "object", "properties": { "type": { "type": "string", "const": "grid", "description": "Which contract template this is." }, "grid": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "A grid's exact terms: pair, levels, quantity and starting sides." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends: no order is placed, and none rests, after it. At most 720 hours after the approval's own expiry." } }, "required": [ "type", "grid", "validUntil" ], "description": "Owner-signed authority for one grid: the resting cell orders its terms derive, until it ends." }, "ApprovalAuthorization": { "type": "object", "properties": { "purpose": { "type": "string", "const": "financial.approval", "description": "Always `financial.approval`: the signature approves this one money action." }, "walletId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet the action spends from." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id, which the signature names, so it approves this approval and no other." }, "request": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval being decided." }, "fingerprint": { "type": "string", "description": "Fingerprint of the immutable approval bytes." }, "tool": { "type": "string", "description": "The exact trusted tool receiving the approved terms." }, "input": { "description": "The complete persisted tool arguments to approve.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ], "description": "Exact financial actions, quantity, allowance, validity and loss bounds authorized by this approval: swap actions, one limit order, one perps transfer/order/cancellation or margin change, one Polymarket funding/order/withdrawal, the exact Solana actions, or one grid's terms." }, "policy": { "description": "The custody worker's exact grant for these terms; clients sign it without mutation.", "$ref": "#/components/schemas/PolicyApprovalMessage" } }, "required": [ "approvalId", "fingerprint", "tool", "input", "contract", "policy" ], "description": "The exact terms the signature covers, including the permission they grant. Shown for review; the signed `message` already contains them." }, "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "purpose", "walletId", "requestKey", "request", "message", "controllerId", "expiresAt" ], "description": "What the user signs to approve a money action. Sign `message` exactly as returned and send the signature to Approve an action with `controllerId` and `expiresAt` unchanged." }, "PolicyApprovalMessage": { "type": "object", "properties": { "domain": { "type": "string", "const": "fin.policy.contract.v1", "description": "Domain separation for this signed policy message." }, "binding": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "testnet", "mainnet" ], "description": "The NEAR network this policy deployment serves." }, "project_uuid": { "type": "string", "minLength": 1, "description": "Stable policy deployment identifier." }, "caller_id": { "type": "string", "minLength": 1, "description": "Fin integration identity bound into consent." } }, "required": [ "network", "project_uuid", "caller_id" ], "description": "The deployment and caller to which this consent applies." }, "owner_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the canonical owner descriptor." }, "wallet_id": { "type": "string", "minLength": 1, "description": "The policy worker's wallet identity receiving this grant; the worker spends only from that wallet's own account." }, "approval_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The exact persisted approval to which this owner-signed grant belongs." }, "nonce": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Unique consent nonce; replay cannot create additional allowance." }, "issued_at_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Consent issue time in Unix milliseconds." }, "source": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "one_shot", "description": "One approved request, executed by the run that asked for it." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "grid", "description": "A standing grid grant: the cell orders its terms derive, placed by the grid engine without a run." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "automation", "description": "A standing grant that the named automation's recorded firings may exercise." }, "definition": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name, as approved." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "The automation's saved prompt, as approved." }, "rule": { "$ref": "#/components/schemas/AutomationRule" } }, "required": [ "name", "prompt", "rule" ], "description": "The automation's exact saved definition; any edit invalidates this consent." }, "maxSigningDelaySeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "The owner-approved time after the worker records a firing during which its run may obtain signatures." }, "automationId": { "description": "The saved automation whose edited terms the owner approves; absent for creation.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "definitionVersion": { "description": "The saved definition version those edited terms authorize; absent for creation.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "kind", "definition", "maxSigningDelaySeconds" ] } ], "description": "What this consent authorizes: one present-user request, the firings of one exact automation, or one grid's derived orders." }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ], "description": "The exact approved authority: swap actions with their bounds, count and expiry, one limit order, one perps transfer/order/cancellation or margin change, one Polymarket funding/order/withdrawal, the exact Solana actions, or one grid." } }, "required": [ "domain", "binding", "owner_id", "wallet_id", "approval_id", "nonce", "issued_at_ms", "source", "contract" ], "description": "Owner-signed authority for one exact financial contract." }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ] } }, "required": [ "intervalSeconds", "readers" ] }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ] }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get an approval 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. `GET /v1/users/{userId}/approvals/{approvalId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "approvalId", "required": true, "description": "The approval's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/approvals/YOUR_APPROVAL_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The approval. ```json { "description": "The approval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "approvals.get", "summary": "Get an approval", "tags": [ "approvals" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "approvalId", "required": true, "description": "The approval's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The approval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "tool": { "type": "string", "description": "The tool the agent wants to use." }, "fingerprint": { "type": "string", "description": "The SHA-256 digest, as 64 lowercase hexadecimal characters, of the tool and its exact input in canonical JSON, with the deployment's no-signing restriction when it set one: the decision applies to exactly this action, and the action that runs must match it." }, "input": { "description": "The tool's input, exactly as it would run: show it to the user.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, { "type": "null" } ], "description": "For a money action, the amounts, assets, destinations and limits approving it allows; `null` for other actions." }, "authorization": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalAuthorization" }, { "type": "null" } ], "description": "For a money action waiting for a decision: the message the user signs to approve it, and the request it covers. `null` for other actions, once decided, and for withdrawals the user starts with Withdraw funds, which approves them itself." }, "summary": { "type": "string", "description": "A short summary of what approving would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "`pending` while it waits for a decision, `approved` or `denied` once decided, or `expired` when nobody decided before `expiresAt`." }, "reason": { "description": "Why it was decided, if a reason was given.", "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the agent asked." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval expires if nobody decides it." }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the approved action started, or `null` until then (always `null` when denied). The action can still fail afterwards: this is not proof it succeeded." }, "signedBy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192 }, { "type": "null" } ], "description": "For an approved money action, which only the user's signature approves: the sign-in wallet that signed it, by its public identifier (an EVM, Solana, Stellar or Tron address, a NEAR account, a TON public key, or a passkey's credential id). A user's sign-in wallet is fixed at their first sign-in and never replaced, so reading it now names the same wallet that signed when the action was approved. `null` for any other approval, and for a money action approved before the user's sign-in wallet was registered, when approvals took no signature." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The run waiting on this approval; `null` only for old approvals." }, "operationId": { "type": "null", "description": "Always `null` for an approval a run is waiting on." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "authorization", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "signedBy", "conversationId", "runId", "operationId" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "tool": { "type": "string", "description": "The tool the agent wants to use." }, "fingerprint": { "type": "string", "description": "The SHA-256 digest, as 64 lowercase hexadecimal characters, of the tool and its exact input in canonical JSON, with the deployment's no-signing restriction when it set one: the decision applies to exactly this action, and the action that runs must match it." }, "input": { "description": "The tool's input, exactly as it would run: show it to the user.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, { "type": "null" } ], "description": "For a money action, the amounts, assets, destinations and limits approving it allows; `null` for other actions." }, "authorization": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalAuthorization" }, { "type": "null" } ], "description": "For a money action waiting for a decision: the message the user signs to approve it, and the request it covers. `null` for other actions, once decided, and for withdrawals the user starts with Withdraw funds, which approves them itself." }, "summary": { "type": "string", "description": "A short summary of what approving would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "`pending` while it waits for a decision, `approved` or `denied` once decided, or `expired` when nobody decided before `expiresAt`." }, "reason": { "description": "Why it was decided, if a reason was given.", "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the agent asked." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval expires if nobody decides it." }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the approved action started, or `null` until then (always `null` when denied). The action can still fail afterwards: this is not proof it succeeded." }, "signedBy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192 }, { "type": "null" } ], "description": "For an approved money action, which only the user's signature approves: the sign-in wallet that signed it, by its public identifier (an EVM, Solana, Stellar or Tron address, a NEAR account, a TON public key, or a passkey's credential id). A user's sign-in wallet is fixed at their first sign-in and never replaced, so reading it now names the same wallet that signed when the action was approved. `null` for any other approval, and for a money action approved before the user's sign-in wallet was registered, when approvals took no signature." }, "conversationId": { "type": "null", "description": "Always `null`: a withdrawal's review belongs to the withdrawal." }, "runId": { "type": "null", "description": "Always `null`: a withdrawal has no run." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal this review belongs to (its `id` in Get a withdrawal). Withdraw funds decides it." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "authorization", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "signedBy", "conversationId", "runId", "operationId" ] } ], "description": "An action the agent wants to take that needs the user's OK: what it would do, and whether the user decided." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "LimitOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "limit_order", "description": "Which contract template this is." }, "order": { "type": "object", "properties": { "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order sells: token id and decimals." } }, "required": [ "pinned" ], "description": "The input (base) asset this order sells." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order buys: token id and decimals." } }, "required": [ "pinned" ], "description": "The output (quote) asset this order buys." }, "quantity": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount to sell, in the input asset's smallest unit. 1 NEAR with verified decimals 24 is \"1000000000000000000000000\". Scale decimal digits with the verified decimals and reject excess fractional digits; no floating-point arithmetic or bash." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The minimum price the fill must reach, as output-asset units per ONE input unit, written as a plain human decimal: \"5\" means at least 5 output tokens per 1 input token. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order may rest before it expires, in whole hours. Use the user's duration within this wallet's maximum, or the wallet's default from the latest request's host context when none is given. The schema permits up to 720 hours (30 days); a wallet may have a lower maximum. Never shorten a requested duration to fit." } }, "required": [ "input", "output", "quantity", "limitPrice", "expiresInHours" ], "description": "The exact approved placement request." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest instant the order may be created and funded under this consent." } }, "required": [ "type", "order", "validUntil" ], "description": "Owner-signed authority for one resting limit order: the exact approved placement, created and funded once by the policy worker before the approval expires." }, "PerpsTransferContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_transfer", "description": "Which authorization contract this is." }, "direction": { "type": "string", "enum": [ "fund", "withdraw" ], "description": "Fund the own perps account from the agent wallet, or withdraw back to the same agent wallet." }, "transfer": { "description": "The exact approved amount and all-in loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PerpsTransferInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "direction", "transfer", "validUntil" ], "description": "One approved perps transfer in exactly the named direction." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "PerpsOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_order", "description": "Which authorization contract this is." }, "order": { "description": "The exact approved order.", "$ref": "#/components/schemas/PerpsOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "order", "validUntil" ], "description": "One approved Hyperliquid order, signed once exactly as approved." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsCancelContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_cancel", "description": "Which authorization contract this is." }, "cancel": { "description": "The exact order approved for cancelling.", "$ref": "#/components/schemas/PerpsCancelInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "cancel", "validUntil" ], "description": "One approved cancellation of one resting Hyperliquid order." }, "PerpsCancelInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "oid": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The resting order's id exactly as perps_orders lists it." } }, "required": [ "coin", "asset", "oid" ], "description": "Cancel one resting order on the agent's own account." }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PerpsMarginContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_margin", "description": "Which authorization contract this is." }, "margin": { "description": "The exact approved margin change.", "$ref": "#/components/schemas/PerpsMarginInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "margin", "validUntil" ], "description": "One approved change to one isolated position's margin, signed once exactly as approved." }, "PerpsMarginInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "change": { "type": "string", "enum": [ "add", "remove" ], "description": "`add` moves USDC from the account into the position's isolated margin, lowering its liquidation risk; `remove` takes it back out, raising that risk. A strict isolated market never lets margin be removed while the position is open." }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,8})(\\.[0-9]{0,5}[1-9])?$", "description": "Exact USDC to move, at most six decimal places, such as `25` or `12.5`." } }, "required": [ "coin", "asset", "change", "amount" ], "description": "Add or remove margin on one isolated position on the agent's own account." }, "PredictionFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_fund", "description": "One approved Polymarket funding transfer." }, "transfer": { "description": "The exact approved USDC or USDT debit and the first leg's loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PredictionFundInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "transfer", "validUntil" ], "description": "One exact USDC or USDT debit delivered as native Base USDC to Polymarket's bridge for the agent's own account; the final pUSD amount is not bounded." }, "PredictionFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact debit in six-decimal atomic units: 5 USDC or USDT is \"5000000\", spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it. The host resolves the agent’s own Polymarket Deposit Wallet and its bridge address; never supply an address." }, "maxFirstLegLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum loss, in basis points, of the first leg only: the wallet's USDC, USDT or coin delivered as native Base USDC to Polymarket's bridge, fees and any cross-chain hop included. It does not bound the bridge's conversion to pUSD on Polygon, whose fees and output are variable and estimated. Required; no default." }, "payWith": { "description": "Approved in chat as one call or as a funded order's funding: the coin the first leg pays with instead of a USDC or USDT holding, and the most of it it may spend.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxFirstLegLossBps" ], "description": "Fund the agent's own Polymarket Deposit Wallet: one exact USDC or USDT debit, or that many dollars of a coin, delivered as native Base USDC to Polymarket's bridge, which credits an estimated, not guaranteed, pUSD amount on Polygon later." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "SolanaFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_fund", "description": "Which authorization contract this is." }, "fund": { "description": "The exact approved amount and loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaFundInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "fund", "maxExecutions", "validUntil" ], "description": "An approved move of USDC or USDT, or a coin, into the agent's own Solana account." }, "SolanaFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to move from the agent wallet into the agent's Solana account as SOL, in six-decimal atomic units: 5 USDC is \"5000000\". Spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." }, "payWith": { "description": "Approved in chat as one call: the coin this funding pays with instead of a USDC or USDT holding, and the most of it it may spend. Never SOL.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "Move an exact amount of USDC or USDT, or that many dollars of a coin, from the agent wallet into its own Solana account as SOL." }, "SolanaWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_withdraw", "description": "Which authorization contract this is." }, "withdraw": { "description": "The exact approved amount, what returns and the loss bound.", "$ref": "#/components/schemas/SolanaWithdrawInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "withdraw", "maxExecutions", "validUntil" ], "description": "An approved move of SOL from the agent's own Solana account back to its agent wallet." }, "SolanaWithdrawInput": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Withdraw an exact amount of SOL." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to withdraw, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Withdraw an exact amount of SOL." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_spendable", "description": "Withdraw all the SOL above the reserve the account keeps for rent and network fees." } }, "required": [ "kind" ], "description": "Withdraw all the spendable SOL." } ], "description": "How much SOL to withdraw from the agent's Solana account." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns it to the agent wallet as USDC on NEAR; `sol` returns it to the agent wallet as SOL." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." } }, "required": [ "amount", "receive", "maxValueLossBps" ], "description": "Move SOL from the agent's own Solana account back to its agent wallet." }, "PredictionOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_order" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "order", "validUntil" ] }, "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "PredictionWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_withdraw" }, "withdrawal": { "$ref": "#/components/schemas/PredictionWithdrawInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ] }, "PredictionWithdrawInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact pUSD debit in six-decimal atomic units: 5 pUSD is \"5000000\". Only the agent’s own Deposit Wallet is spent." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "amountRaw", "maxLossBps" ], "description": "Withdraw pUSD through Polymarket’s conversion service as native USDC on Polygon to a unique verified 1Click address crediting only the agent’s own confidential Intents wallet. Funding remains a separate USDC route." }, "CompositeContract": { "type": "object", "properties": { "type": { "type": "string", "const": "composite", "description": "Which authorization contract this is." }, "pieces": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "intents_execute", "perps_fund", "perps_order_place", "prediction_fund", "prediction_order_place", "perps_withdraw", "prediction_withdraw" ], "description": "The tool whose one-shot call this piece is." }, "contract": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, "startBy": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "tool", "contract", "startBy" ] } }, "dependencies": { "type": "array", "items": { "maxItems": 6, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "walletDebit": { "anyOf": [ { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, { "type": "array", "prefixItems": [], "items": false, "maxItems": 0 } ], "description": "The sum of every piece's debit from the agent wallet, per token, in raw units. Empty when the pieces are venue orders paid from money already on their venues, as when finishing a basket, or a cash-out, which closes a position and brings home what that freed." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When every piece that has not started loses its authority." } }, "required": [ "type", "pieces", "dependencies", "walletDebit", "validUntil" ], "description": "One owner signature over several exact one-shot grants and the order they run in." }, "PerpsFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_freed_withdrawal", "description": "Which authorization contract this is." }, "withdrawal": { "description": "The signed maximum and all-in loss bound of the withdrawal home.", "$ref": "#/components/schemas/PerpsFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's exit freed on Hyperliquid, at most the signed maximum. Only ever a piece of a cash-out." }, "PerpsFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic USDC: what the exit before it frees, sized by the host before the approval opens. Never more than the exit freed." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." } }, "required": [ "upToRaw", "maxValueLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the exit before it freed on its own Hyperliquid account, never more than upToRaw." }, "PredictionFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_freed_withdrawal" }, "withdrawal": { "$ref": "#/components/schemas/PredictionFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's sale freed on Polymarket, at most the signed maximum. Only ever a piece of a cash-out." }, "PredictionFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic pUSD: what the sale before it frees, sized by the host before the approval opens. Never more than the sale freed." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "upToRaw", "maxLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the sale before it freed in its own Polymarket Deposit Wallet, never more than upToRaw." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaSellManyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell_many", "description": "Which authorization contract this is." }, "sellMany": { "description": "The exact approved coins, amounts and loss bounds, in order, and where the proceeds go.", "$ref": "#/components/schemas/SolanaSellManyInput" }, "maxExecutions": { "type": "number", "const": 1, "description": "A multi-coin sale is approved once and runs once: always 1." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sellMany", "maxExecutions", "validUntil" ], "description": "An approved multi-coin Solana sale, executed only exactly as approved." }, "SolanaSellManyInput": { "type": "object", "properties": { "sells": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/SolanaSale" }, "description": "The coins to sell, in the order they are sold: 2 to 6, each a different mint, none of them SOL itself." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the summed proceeds of every sale that went through to the agent wallet as USDC on NEAR, in one transfer once the last sale ran; `sol` keeps them as SOL in the agent's Solana account." } }, "required": [ "sells", "receive" ], "description": "Several sells of Solana tokens held in the agent's own Solana account, approved together and run as one: each sale on its own, one after another, then one transfer of what they returned." }, "SolanaSale": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "maxValueLossBps" ], "description": "One coin of a multi-coin sale, sold through the agent's own Solana account." }, "GridContract": { "type": "object", "properties": { "type": { "type": "string", "const": "grid", "description": "Which contract template this is." }, "grid": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "A grid's exact terms: pair, levels, quantity and starting sides." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends: no order is placed, and none rests, after it. At most 720 hours after the approval's own expiry." } }, "required": [ "type", "grid", "validUntil" ], "description": "Owner-signed authority for one grid: the resting cell orders its terms derive, until it ends." }, "ApprovalAuthorization": { "type": "object", "properties": { "purpose": { "type": "string", "const": "financial.approval", "description": "Always `financial.approval`: the signature approves this one money action." }, "walletId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet the action spends from." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id, which the signature names, so it approves this approval and no other." }, "request": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval being decided." }, "fingerprint": { "type": "string", "description": "Fingerprint of the immutable approval bytes." }, "tool": { "type": "string", "description": "The exact trusted tool receiving the approved terms." }, "input": { "description": "The complete persisted tool arguments to approve.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ], "description": "Exact financial actions, quantity, allowance, validity and loss bounds authorized by this approval: swap actions, one limit order, one perps transfer/order/cancellation or margin change, one Polymarket funding/order/withdrawal, the exact Solana actions, or one grid's terms." }, "policy": { "description": "The custody worker's exact grant for these terms; clients sign it without mutation.", "$ref": "#/components/schemas/PolicyApprovalMessage" } }, "required": [ "approvalId", "fingerprint", "tool", "input", "contract", "policy" ], "description": "The exact terms the signature covers, including the permission they grant. Shown for review; the signed `message` already contains them." }, "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "purpose", "walletId", "requestKey", "request", "message", "controllerId", "expiresAt" ], "description": "What the user signs to approve a money action. Sign `message` exactly as returned and send the signature to Approve an action with `controllerId` and `expiresAt` unchanged." }, "PolicyApprovalMessage": { "type": "object", "properties": { "domain": { "type": "string", "const": "fin.policy.contract.v1", "description": "Domain separation for this signed policy message." }, "binding": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "testnet", "mainnet" ], "description": "The NEAR network this policy deployment serves." }, "project_uuid": { "type": "string", "minLength": 1, "description": "Stable policy deployment identifier." }, "caller_id": { "type": "string", "minLength": 1, "description": "Fin integration identity bound into consent." } }, "required": [ "network", "project_uuid", "caller_id" ], "description": "The deployment and caller to which this consent applies." }, "owner_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the canonical owner descriptor." }, "wallet_id": { "type": "string", "minLength": 1, "description": "The policy worker's wallet identity receiving this grant; the worker spends only from that wallet's own account." }, "approval_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The exact persisted approval to which this owner-signed grant belongs." }, "nonce": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Unique consent nonce; replay cannot create additional allowance." }, "issued_at_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Consent issue time in Unix milliseconds." }, "source": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "one_shot", "description": "One approved request, executed by the run that asked for it." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "grid", "description": "A standing grid grant: the cell orders its terms derive, placed by the grid engine without a run." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "automation", "description": "A standing grant that the named automation's recorded firings may exercise." }, "definition": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name, as approved." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "The automation's saved prompt, as approved." }, "rule": { "$ref": "#/components/schemas/AutomationRule" } }, "required": [ "name", "prompt", "rule" ], "description": "The automation's exact saved definition; any edit invalidates this consent." }, "maxSigningDelaySeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "The owner-approved time after the worker records a firing during which its run may obtain signatures." }, "automationId": { "description": "The saved automation whose edited terms the owner approves; absent for creation.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "definitionVersion": { "description": "The saved definition version those edited terms authorize; absent for creation.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "kind", "definition", "maxSigningDelaySeconds" ] } ], "description": "What this consent authorizes: one present-user request, the firings of one exact automation, or one grid's derived orders." }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ], "description": "The exact approved authority: swap actions with their bounds, count and expiry, one limit order, one perps transfer/order/cancellation or margin change, one Polymarket funding/order/withdrawal, the exact Solana actions, or one grid." } }, "required": [ "domain", "binding", "owner_id", "wallet_id", "approval_id", "nonce", "issued_at_ms", "source", "contract" ], "description": "Owner-signed authority for one exact financial contract." }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ] } }, "required": [ "intervalSeconds", "readers" ] }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ] }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Approve an action 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. `POST /v1/users/{userId}/approvals/{approvalId}/approve` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "approvalId", "required": true, "description": "The approval's id." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization": { "description": "For a money action: the user's signature of `authorization.message` from Get an approval, with its `controllerId` and `expiresAt` unchanged. Not needed for other actions.", "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "An EIP-191 personal-message signature by the current controller.", "enum": [ "evm" ] }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A user-verified WebAuthn assertion over the message digest.", "enum": [ "webauthn" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience.", "enum": [ "near" ] }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes.", "enum": [ "solana" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message).", "enum": [ "stellar" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message.", "enum": [ "ton" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TIP-191 `signMessageV2` signature over the exact message.", "enum": [ "tron" ] }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false }, "reason": { "description": "Why the call was approved, for the record.", "type": "string", "maxLength": 1024 }, "attestation": { "description": "A partner-side confirmation reference, recorded on the journal event; never verified by fin.", "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The partner's own reference for this confirmation." } }, "required": [ "reference" ], "additionalProperties": false } }, "additionalProperties": false } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/approvals/YOUR_APPROVAL_ID/approve' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{}' ``` ## Responses ### 200 The approval, now approved. ```json { "description": "The approval, now approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `approval_not_pending` — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation - `run_active` — a run already holds this conversation - `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed ```json { "description": "The operation lost to the current state.\n\n- `approval_not_pending` — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `run_active` — a run already holds this conversation\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `execution_capacity` — no capacity is free to run this right now; honour `Retry-After` - `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "approvals.approve", "summary": "Approve an action", "tags": [ "approvals" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization": { "description": "For a money action: the user's signature of `authorization.message` from Get an approval, with its `controllerId` and `expiresAt` unchanged. Not needed for other actions.", "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "An EIP-191 personal-message signature by the current controller.", "enum": [ "evm" ] }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A user-verified WebAuthn assertion over the message digest.", "enum": [ "webauthn" ] }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience.", "enum": [ "near" ] }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes.", "enum": [ "solana" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message).", "enum": [ "stellar" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message.", "enum": [ "ton" ] }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "A TIP-191 `signMessageV2` signature over the exact message.", "enum": [ "tron" ] }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false }, "reason": { "description": "Why the call was approved, for the record.", "type": "string", "maxLength": 1024 }, "attestation": { "description": "A partner-side confirmation reference, recorded on the journal event; never verified by fin.", "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The partner's own reference for this confirmation." } }, "required": [ "reference" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "approvalId", "required": true, "description": "The approval's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The approval, now approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `approval_not_pending` — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `run_active` — a run already holds this conversation\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "Approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "tool": { "type": "string", "description": "The tool the agent wants to use." }, "fingerprint": { "type": "string", "description": "The SHA-256 digest, as 64 lowercase hexadecimal characters, of the tool and its exact input in canonical JSON, with the deployment's no-signing restriction when it set one: the decision applies to exactly this action, and the action that runs must match it." }, "input": { "description": "The tool's input, exactly as it would run: show it to the user.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, { "type": "null" } ], "description": "For a money action, the amounts, assets, destinations and limits approving it allows; `null` for other actions." }, "authorization": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalAuthorization" }, { "type": "null" } ], "description": "For a money action waiting for a decision: the message the user signs to approve it, and the request it covers. `null` for other actions, once decided, and for withdrawals the user starts with Withdraw funds, which approves them itself." }, "summary": { "type": "string", "description": "A short summary of what approving would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "`pending` while it waits for a decision, `approved` or `denied` once decided, or `expired` when nobody decided before `expiresAt`." }, "reason": { "description": "Why it was decided, if a reason was given.", "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the agent asked." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval expires if nobody decides it." }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the approved action started, or `null` until then (always `null` when denied). The action can still fail afterwards: this is not proof it succeeded." }, "signedBy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192 }, { "type": "null" } ], "description": "For an approved money action, which only the user's signature approves: the sign-in wallet that signed it, by its public identifier (an EVM, Solana, Stellar or Tron address, a NEAR account, a TON public key, or a passkey's credential id). A user's sign-in wallet is fixed at their first sign-in and never replaced, so reading it now names the same wallet that signed when the action was approved. `null` for any other approval, and for a money action approved before the user's sign-in wallet was registered, when approvals took no signature." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The run waiting on this approval; `null` only for old approvals." }, "operationId": { "type": "null", "description": "Always `null` for an approval a run is waiting on." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "authorization", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "signedBy", "conversationId", "runId", "operationId" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "tool": { "type": "string", "description": "The tool the agent wants to use." }, "fingerprint": { "type": "string", "description": "The SHA-256 digest, as 64 lowercase hexadecimal characters, of the tool and its exact input in canonical JSON, with the deployment's no-signing restriction when it set one: the decision applies to exactly this action, and the action that runs must match it." }, "input": { "description": "The tool's input, exactly as it would run: show it to the user.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, { "type": "null" } ], "description": "For a money action, the amounts, assets, destinations and limits approving it allows; `null` for other actions." }, "authorization": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalAuthorization" }, { "type": "null" } ], "description": "For a money action waiting for a decision: the message the user signs to approve it, and the request it covers. `null` for other actions, once decided, and for withdrawals the user starts with Withdraw funds, which approves them itself." }, "summary": { "type": "string", "description": "A short summary of what approving would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "`pending` while it waits for a decision, `approved` or `denied` once decided, or `expired` when nobody decided before `expiresAt`." }, "reason": { "description": "Why it was decided, if a reason was given.", "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the agent asked." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval expires if nobody decides it." }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the approved action started, or `null` until then (always `null` when denied). The action can still fail afterwards: this is not proof it succeeded." }, "signedBy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192 }, { "type": "null" } ], "description": "For an approved money action, which only the user's signature approves: the sign-in wallet that signed it, by its public identifier (an EVM, Solana, Stellar or Tron address, a NEAR account, a TON public key, or a passkey's credential id). A user's sign-in wallet is fixed at their first sign-in and never replaced, so reading it now names the same wallet that signed when the action was approved. `null` for any other approval, and for a money action approved before the user's sign-in wallet was registered, when approvals took no signature." }, "conversationId": { "type": "null", "description": "Always `null`: a withdrawal's review belongs to the withdrawal." }, "runId": { "type": "null", "description": "Always `null`: a withdrawal has no run." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal this review belongs to (its `id` in Get a withdrawal). Withdraw funds decides it." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "authorization", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "signedBy", "conversationId", "runId", "operationId" ] } ], "description": "An action the agent wants to take that needs the user's OK: what it would do, and whether the user decided." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "LimitOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "limit_order", "description": "Which contract template this is." }, "order": { "type": "object", "properties": { "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order sells: token id and decimals." } }, "required": [ "pinned" ], "description": "The input (base) asset this order sells." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order buys: token id and decimals." } }, "required": [ "pinned" ], "description": "The output (quote) asset this order buys." }, "quantity": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount to sell, in the input asset's smallest unit. 1 NEAR with verified decimals 24 is \"1000000000000000000000000\". Scale decimal digits with the verified decimals and reject excess fractional digits; no floating-point arithmetic or bash." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The minimum price the fill must reach, as output-asset units per ONE input unit, written as a plain human decimal: \"5\" means at least 5 output tokens per 1 input token. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order may rest before it expires, in whole hours. Use the user's duration within this wallet's maximum, or the wallet's default from the latest request's host context when none is given. The schema permits up to 720 hours (30 days); a wallet may have a lower maximum. Never shorten a requested duration to fit." } }, "required": [ "input", "output", "quantity", "limitPrice", "expiresInHours" ], "description": "The exact approved placement request." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest instant the order may be created and funded under this consent." } }, "required": [ "type", "order", "validUntil" ], "description": "Owner-signed authority for one resting limit order: the exact approved placement, created and funded once by the policy worker before the approval expires." }, "PerpsTransferContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_transfer", "description": "Which authorization contract this is." }, "direction": { "type": "string", "enum": [ "fund", "withdraw" ], "description": "Fund the own perps account from the agent wallet, or withdraw back to the same agent wallet." }, "transfer": { "description": "The exact approved amount and all-in loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PerpsTransferInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "direction", "transfer", "validUntil" ], "description": "One approved perps transfer in exactly the named direction." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "PerpsOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_order", "description": "Which authorization contract this is." }, "order": { "description": "The exact approved order.", "$ref": "#/components/schemas/PerpsOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "order", "validUntil" ], "description": "One approved Hyperliquid order, signed once exactly as approved." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsCancelContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_cancel", "description": "Which authorization contract this is." }, "cancel": { "description": "The exact order approved for cancelling.", "$ref": "#/components/schemas/PerpsCancelInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "cancel", "validUntil" ], "description": "One approved cancellation of one resting Hyperliquid order." }, "PerpsCancelInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "oid": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The resting order's id exactly as perps_orders lists it." } }, "required": [ "coin", "asset", "oid" ], "description": "Cancel one resting order on the agent's own account." }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PerpsMarginContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_margin", "description": "Which authorization contract this is." }, "margin": { "description": "The exact approved margin change.", "$ref": "#/components/schemas/PerpsMarginInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "margin", "validUntil" ], "description": "One approved change to one isolated position's margin, signed once exactly as approved." }, "PerpsMarginInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "change": { "type": "string", "enum": [ "add", "remove" ], "description": "`add` moves USDC from the account into the position's isolated margin, lowering its liquidation risk; `remove` takes it back out, raising that risk. A strict isolated market never lets margin be removed while the position is open." }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,8})(\\.[0-9]{0,5}[1-9])?$", "description": "Exact USDC to move, at most six decimal places, such as `25` or `12.5`." } }, "required": [ "coin", "asset", "change", "amount" ], "description": "Add or remove margin on one isolated position on the agent's own account." }, "PredictionFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_fund", "description": "One approved Polymarket funding transfer." }, "transfer": { "description": "The exact approved USDC or USDT debit and the first leg's loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PredictionFundInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "transfer", "validUntil" ], "description": "One exact USDC or USDT debit delivered as native Base USDC to Polymarket's bridge for the agent's own account; the final pUSD amount is not bounded." }, "PredictionFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact debit in six-decimal atomic units: 5 USDC or USDT is \"5000000\", spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it. The host resolves the agent’s own Polymarket Deposit Wallet and its bridge address; never supply an address." }, "maxFirstLegLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum loss, in basis points, of the first leg only: the wallet's USDC, USDT or coin delivered as native Base USDC to Polymarket's bridge, fees and any cross-chain hop included. It does not bound the bridge's conversion to pUSD on Polygon, whose fees and output are variable and estimated. Required; no default." }, "payWith": { "description": "Approved in chat as one call or as a funded order's funding: the coin the first leg pays with instead of a USDC or USDT holding, and the most of it it may spend.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxFirstLegLossBps" ], "description": "Fund the agent's own Polymarket Deposit Wallet: one exact USDC or USDT debit, or that many dollars of a coin, delivered as native Base USDC to Polymarket's bridge, which credits an estimated, not guaranteed, pUSD amount on Polygon later." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "SolanaFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_fund", "description": "Which authorization contract this is." }, "fund": { "description": "The exact approved amount and loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaFundInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "fund", "maxExecutions", "validUntil" ], "description": "An approved move of USDC or USDT, or a coin, into the agent's own Solana account." }, "SolanaFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to move from the agent wallet into the agent's Solana account as SOL, in six-decimal atomic units: 5 USDC is \"5000000\". Spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." }, "payWith": { "description": "Approved in chat as one call: the coin this funding pays with instead of a USDC or USDT holding, and the most of it it may spend. Never SOL.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "Move an exact amount of USDC or USDT, or that many dollars of a coin, from the agent wallet into its own Solana account as SOL." }, "SolanaWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_withdraw", "description": "Which authorization contract this is." }, "withdraw": { "description": "The exact approved amount, what returns and the loss bound.", "$ref": "#/components/schemas/SolanaWithdrawInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "withdraw", "maxExecutions", "validUntil" ], "description": "An approved move of SOL from the agent's own Solana account back to its agent wallet." }, "SolanaWithdrawInput": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Withdraw an exact amount of SOL." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to withdraw, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Withdraw an exact amount of SOL." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_spendable", "description": "Withdraw all the SOL above the reserve the account keeps for rent and network fees." } }, "required": [ "kind" ], "description": "Withdraw all the spendable SOL." } ], "description": "How much SOL to withdraw from the agent's Solana account." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns it to the agent wallet as USDC on NEAR; `sol` returns it to the agent wallet as SOL." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." } }, "required": [ "amount", "receive", "maxValueLossBps" ], "description": "Move SOL from the agent's own Solana account back to its agent wallet." }, "PredictionOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_order" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "order", "validUntil" ] }, "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "PredictionWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_withdraw" }, "withdrawal": { "$ref": "#/components/schemas/PredictionWithdrawInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ] }, "PredictionWithdrawInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact pUSD debit in six-decimal atomic units: 5 pUSD is \"5000000\". Only the agent’s own Deposit Wallet is spent." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "amountRaw", "maxLossBps" ], "description": "Withdraw pUSD through Polymarket’s conversion service as native USDC on Polygon to a unique verified 1Click address crediting only the agent’s own confidential Intents wallet. Funding remains a separate USDC route." }, "CompositeContract": { "type": "object", "properties": { "type": { "type": "string", "const": "composite", "description": "Which authorization contract this is." }, "pieces": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "intents_execute", "perps_fund", "perps_order_place", "prediction_fund", "prediction_order_place", "perps_withdraw", "prediction_withdraw" ], "description": "The tool whose one-shot call this piece is." }, "contract": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, "startBy": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "tool", "contract", "startBy" ] } }, "dependencies": { "type": "array", "items": { "maxItems": 6, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "walletDebit": { "anyOf": [ { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, { "type": "array", "prefixItems": [], "items": false, "maxItems": 0 } ], "description": "The sum of every piece's debit from the agent wallet, per token, in raw units. Empty when the pieces are venue orders paid from money already on their venues, as when finishing a basket, or a cash-out, which closes a position and brings home what that freed." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When every piece that has not started loses its authority." } }, "required": [ "type", "pieces", "dependencies", "walletDebit", "validUntil" ], "description": "One owner signature over several exact one-shot grants and the order they run in." }, "PerpsFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_freed_withdrawal", "description": "Which authorization contract this is." }, "withdrawal": { "description": "The signed maximum and all-in loss bound of the withdrawal home.", "$ref": "#/components/schemas/PerpsFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's exit freed on Hyperliquid, at most the signed maximum. Only ever a piece of a cash-out." }, "PerpsFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic USDC: what the exit before it frees, sized by the host before the approval opens. Never more than the exit freed." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." } }, "required": [ "upToRaw", "maxValueLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the exit before it freed on its own Hyperliquid account, never more than upToRaw." }, "PredictionFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_freed_withdrawal" }, "withdrawal": { "$ref": "#/components/schemas/PredictionFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's sale freed on Polymarket, at most the signed maximum. Only ever a piece of a cash-out." }, "PredictionFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic pUSD: what the sale before it frees, sized by the host before the approval opens. Never more than the sale freed." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "upToRaw", "maxLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the sale before it freed in its own Polymarket Deposit Wallet, never more than upToRaw." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaSellManyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell_many", "description": "Which authorization contract this is." }, "sellMany": { "description": "The exact approved coins, amounts and loss bounds, in order, and where the proceeds go.", "$ref": "#/components/schemas/SolanaSellManyInput" }, "maxExecutions": { "type": "number", "const": 1, "description": "A multi-coin sale is approved once and runs once: always 1." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sellMany", "maxExecutions", "validUntil" ], "description": "An approved multi-coin Solana sale, executed only exactly as approved." }, "SolanaSellManyInput": { "type": "object", "properties": { "sells": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/SolanaSale" }, "description": "The coins to sell, in the order they are sold: 2 to 6, each a different mint, none of them SOL itself." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the summed proceeds of every sale that went through to the agent wallet as USDC on NEAR, in one transfer once the last sale ran; `sol` keeps them as SOL in the agent's Solana account." } }, "required": [ "sells", "receive" ], "description": "Several sells of Solana tokens held in the agent's own Solana account, approved together and run as one: each sale on its own, one after another, then one transfer of what they returned." }, "SolanaSale": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "maxValueLossBps" ], "description": "One coin of a multi-coin sale, sold through the agent's own Solana account." }, "GridContract": { "type": "object", "properties": { "type": { "type": "string", "const": "grid", "description": "Which contract template this is." }, "grid": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "A grid's exact terms: pair, levels, quantity and starting sides." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends: no order is placed, and none rests, after it. At most 720 hours after the approval's own expiry." } }, "required": [ "type", "grid", "validUntil" ], "description": "Owner-signed authority for one grid: the resting cell orders its terms derive, until it ends." }, "ApprovalAuthorization": { "type": "object", "properties": { "purpose": { "type": "string", "const": "financial.approval", "description": "Always `financial.approval`: the signature approves this one money action." }, "walletId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet the action spends from." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id, which the signature names, so it approves this approval and no other." }, "request": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval being decided." }, "fingerprint": { "type": "string", "description": "Fingerprint of the immutable approval bytes." }, "tool": { "type": "string", "description": "The exact trusted tool receiving the approved terms." }, "input": { "description": "The complete persisted tool arguments to approve.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ], "description": "Exact financial actions, quantity, allowance, validity and loss bounds authorized by this approval: swap actions, one limit order, one perps transfer/order/cancellation or margin change, one Polymarket funding/order/withdrawal, the exact Solana actions, or one grid's terms." }, "policy": { "description": "The custody worker's exact grant for these terms; clients sign it without mutation.", "$ref": "#/components/schemas/PolicyApprovalMessage" } }, "required": [ "approvalId", "fingerprint", "tool", "input", "contract", "policy" ], "description": "The exact terms the signature covers, including the permission they grant. Shown for review; the signed `message` already contains them." }, "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "purpose", "walletId", "requestKey", "request", "message", "controllerId", "expiresAt" ], "description": "What the user signs to approve a money action. Sign `message` exactly as returned and send the signature to Approve an action with `controllerId` and `expiresAt` unchanged." }, "PolicyApprovalMessage": { "type": "object", "properties": { "domain": { "type": "string", "const": "fin.policy.contract.v1", "description": "Domain separation for this signed policy message." }, "binding": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "testnet", "mainnet" ], "description": "The NEAR network this policy deployment serves." }, "project_uuid": { "type": "string", "minLength": 1, "description": "Stable policy deployment identifier." }, "caller_id": { "type": "string", "minLength": 1, "description": "Fin integration identity bound into consent." } }, "required": [ "network", "project_uuid", "caller_id" ], "description": "The deployment and caller to which this consent applies." }, "owner_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the canonical owner descriptor." }, "wallet_id": { "type": "string", "minLength": 1, "description": "The policy worker's wallet identity receiving this grant; the worker spends only from that wallet's own account." }, "approval_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The exact persisted approval to which this owner-signed grant belongs." }, "nonce": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Unique consent nonce; replay cannot create additional allowance." }, "issued_at_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Consent issue time in Unix milliseconds." }, "source": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "one_shot", "description": "One approved request, executed by the run that asked for it." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "grid", "description": "A standing grid grant: the cell orders its terms derive, placed by the grid engine without a run." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "automation", "description": "A standing grant that the named automation's recorded firings may exercise." }, "definition": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name, as approved." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "The automation's saved prompt, as approved." }, "rule": { "$ref": "#/components/schemas/AutomationRule" } }, "required": [ "name", "prompt", "rule" ], "description": "The automation's exact saved definition; any edit invalidates this consent." }, "maxSigningDelaySeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "The owner-approved time after the worker records a firing during which its run may obtain signatures." }, "automationId": { "description": "The saved automation whose edited terms the owner approves; absent for creation.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "definitionVersion": { "description": "The saved definition version those edited terms authorize; absent for creation.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "kind", "definition", "maxSigningDelaySeconds" ] } ], "description": "What this consent authorizes: one present-user request, the firings of one exact automation, or one grid's derived orders." }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ], "description": "The exact approved authority: swap actions with their bounds, count and expiry, one limit order, one perps transfer/order/cancellation or margin change, one Polymarket funding/order/withdrawal, the exact Solana actions, or one grid." } }, "required": [ "domain", "binding", "owner_id", "wallet_id", "approval_id", "nonce", "issued_at_ms", "source", "contract" ], "description": "Owner-signed authority for one exact financial contract." }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ] } }, "required": [ "intervalSeconds", "readers" ] }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ] }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Deny an action Records the user's refusal and resumes the paused run, which carries on without the action. Returns the approval. `POST /v1/users/{userId}/approvals/{approvalId}/deny` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "approvalId", "required": true, "description": "The approval's id." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "description": "Why the call was denied, for the record.", "type": "string", "maxLength": 1024 } }, "additionalProperties": false } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/approvals/YOUR_APPROVAL_ID/deny' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{}' ``` ## Responses ### 200 The approval, now denied. ```json { "description": "The approval, now denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `approval_not_pending` — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation - `run_active` — a run already holds this conversation - `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed ```json { "description": "The operation lost to the current state.\n\n- `approval_not_pending` — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `run_active` — a run already holds this conversation\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `execution_capacity` — no capacity is free to run this right now; honour `Retry-After` - `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "approvals.deny", "summary": "Deny an action", "tags": [ "approvals" ], "description": "Records the user's refusal and resumes the paused run, which carries on without the action. Returns the approval.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "description": "Why the call was denied, for the record.", "type": "string", "maxLength": 1024 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "approvalId", "required": true, "description": "The approval's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The approval, now denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `approval_not_pending` — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `run_active` — a run already holds this conversation\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "Approval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "tool": { "type": "string", "description": "The tool the agent wants to use." }, "fingerprint": { "type": "string", "description": "The SHA-256 digest, as 64 lowercase hexadecimal characters, of the tool and its exact input in canonical JSON, with the deployment's no-signing restriction when it set one: the decision applies to exactly this action, and the action that runs must match it." }, "input": { "description": "The tool's input, exactly as it would run: show it to the user.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, { "type": "null" } ], "description": "For a money action, the amounts, assets, destinations and limits approving it allows; `null` for other actions." }, "authorization": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalAuthorization" }, { "type": "null" } ], "description": "For a money action waiting for a decision: the message the user signs to approve it, and the request it covers. `null` for other actions, once decided, and for withdrawals the user starts with Withdraw funds, which approves them itself." }, "summary": { "type": "string", "description": "A short summary of what approving would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "`pending` while it waits for a decision, `approved` or `denied` once decided, or `expired` when nobody decided before `expiresAt`." }, "reason": { "description": "Why it was decided, if a reason was given.", "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the agent asked." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval expires if nobody decides it." }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the approved action started, or `null` until then (always `null` when denied). The action can still fail afterwards: this is not proof it succeeded." }, "signedBy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192 }, { "type": "null" } ], "description": "For an approved money action, which only the user's signature approves: the sign-in wallet that signed it, by its public identifier (an EVM, Solana, Stellar or Tron address, a NEAR account, a TON public key, or a passkey's credential id). A user's sign-in wallet is fixed at their first sign-in and never replaced, so reading it now names the same wallet that signed when the action was approved. `null` for any other approval, and for a money action approved before the user's sign-in wallet was registered, when approvals took no signature." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The run waiting on this approval; `null` only for old approvals." }, "operationId": { "type": "null", "description": "Always `null` for an approval a run is waiting on." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "authorization", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "signedBy", "conversationId", "runId", "operationId" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "tool": { "type": "string", "description": "The tool the agent wants to use." }, "fingerprint": { "type": "string", "description": "The SHA-256 digest, as 64 lowercase hexadecimal characters, of the tool and its exact input in canonical JSON, with the deployment's no-signing restriction when it set one: the decision applies to exactly this action, and the action that runs must match it." }, "input": { "description": "The tool's input, exactly as it would run: show it to the user.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, { "type": "null" } ], "description": "For a money action, the amounts, assets, destinations and limits approving it allows; `null` for other actions." }, "authorization": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalAuthorization" }, { "type": "null" } ], "description": "For a money action waiting for a decision: the message the user signs to approve it, and the request it covers. `null` for other actions, once decided, and for withdrawals the user starts with Withdraw funds, which approves them itself." }, "summary": { "type": "string", "description": "A short summary of what approving would do." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "`pending` while it waits for a decision, `approved` or `denied` once decided, or `expired` when nobody decided before `expiresAt`." }, "reason": { "description": "Why it was decided, if a reason was given.", "type": [ "string", "null" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the agent asked." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval expires if nobody decides it." }, "decidedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was approved or denied; null until then." }, "consumedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the approved action started, or `null` until then (always `null` when denied). The action can still fail afterwards: this is not proof it succeeded." }, "signedBy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192 }, { "type": "null" } ], "description": "For an approved money action, which only the user's signature approves: the sign-in wallet that signed it, by its public identifier (an EVM, Solana, Stellar or Tron address, a NEAR account, a TON public key, or a passkey's credential id). A user's sign-in wallet is fixed at their first sign-in and never replaced, so reading it now names the same wallet that signed when the action was approved. `null` for any other approval, and for a money action approved before the user's sign-in wallet was registered, when approvals took no signature." }, "conversationId": { "type": "null", "description": "Always `null`: a withdrawal's review belongs to the withdrawal." }, "runId": { "type": "null", "description": "Always `null`: a withdrawal has no run." }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal this review belongs to (its `id` in Get a withdrawal). Withdraw funds decides it." } }, "required": [ "id", "tool", "fingerprint", "input", "contract", "authorization", "summary", "status", "reason", "requestedAt", "expiresAt", "decidedAt", "consumedAt", "signedBy", "conversationId", "runId", "operationId" ] } ], "description": "An action the agent wants to take that needs the user's OK: what it would do, and whether the user decided." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "LimitOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "limit_order", "description": "Which contract template this is." }, "order": { "type": "object", "properties": { "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order sells: token id and decimals." } }, "required": [ "pinned" ], "description": "The input (base) asset this order sells." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact asset the order buys: token id and decimals." } }, "required": [ "pinned" ], "description": "The output (quote) asset this order buys." }, "quantity": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount to sell, in the input asset's smallest unit. 1 NEAR with verified decimals 24 is \"1000000000000000000000000\". Scale decimal digits with the verified decimals and reject excess fractional digits; no floating-point arithmetic or bash." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The minimum price the fill must reach, as output-asset units per ONE input unit, written as a plain human decimal: \"5\" means at least 5 output tokens per 1 input token. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order may rest before it expires, in whole hours. Use the user's duration within this wallet's maximum, or the wallet's default from the latest request's host context when none is given. The schema permits up to 720 hours (30 days); a wallet may have a lower maximum. Never shorten a requested duration to fit." } }, "required": [ "input", "output", "quantity", "limitPrice", "expiresInHours" ], "description": "The exact approved placement request." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest instant the order may be created and funded under this consent." } }, "required": [ "type", "order", "validUntil" ], "description": "Owner-signed authority for one resting limit order: the exact approved placement, created and funded once by the policy worker before the approval expires." }, "PerpsTransferContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_transfer", "description": "Which authorization contract this is." }, "direction": { "type": "string", "enum": [ "fund", "withdraw" ], "description": "Fund the own perps account from the agent wallet, or withdraw back to the same agent wallet." }, "transfer": { "description": "The exact approved amount and all-in loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PerpsTransferInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "direction", "transfer", "validUntil" ], "description": "One approved perps transfer in exactly the named direction." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "PerpsOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_order", "description": "Which authorization contract this is." }, "order": { "description": "The exact approved order.", "$ref": "#/components/schemas/PerpsOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "order", "validUntil" ], "description": "One approved Hyperliquid order, signed once exactly as approved." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsCancelContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_cancel", "description": "Which authorization contract this is." }, "cancel": { "description": "The exact order approved for cancelling.", "$ref": "#/components/schemas/PerpsCancelInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "cancel", "validUntil" ], "description": "One approved cancellation of one resting Hyperliquid order." }, "PerpsCancelInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "oid": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The resting order's id exactly as perps_orders lists it." } }, "required": [ "coin", "asset", "oid" ], "description": "Cancel one resting order on the agent's own account." }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PerpsMarginContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_margin", "description": "Which authorization contract this is." }, "margin": { "description": "The exact approved margin change.", "$ref": "#/components/schemas/PerpsMarginInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "margin", "validUntil" ], "description": "One approved change to one isolated position's margin, signed once exactly as approved." }, "PerpsMarginInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "change": { "type": "string", "enum": [ "add", "remove" ], "description": "`add` moves USDC from the account into the position's isolated margin, lowering its liquidation risk; `remove` takes it back out, raising that risk. A strict isolated market never lets margin be removed while the position is open." }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,8})(\\.[0-9]{0,5}[1-9])?$", "description": "Exact USDC to move, at most six decimal places, such as `25` or `12.5`." } }, "required": [ "coin", "asset", "change", "amount" ], "description": "Add or remove margin on one isolated position on the agent's own account." }, "PredictionFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_fund", "description": "One approved Polymarket funding transfer." }, "transfer": { "description": "The exact approved USDC or USDT debit and the first leg's loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/PredictionFundInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "transfer", "validUntil" ], "description": "One exact USDC or USDT debit delivered as native Base USDC to Polymarket's bridge for the agent's own account; the final pUSD amount is not bounded." }, "PredictionFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact debit in six-decimal atomic units: 5 USDC or USDT is \"5000000\", spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it. The host resolves the agent’s own Polymarket Deposit Wallet and its bridge address; never supply an address." }, "maxFirstLegLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum loss, in basis points, of the first leg only: the wallet's USDC, USDT or coin delivered as native Base USDC to Polymarket's bridge, fees and any cross-chain hop included. It does not bound the bridge's conversion to pUSD on Polygon, whose fees and output are variable and estimated. Required; no default." }, "payWith": { "description": "Approved in chat as one call or as a funded order's funding: the coin the first leg pays with instead of a USDC or USDT holding, and the most of it it may spend.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxFirstLegLossBps" ], "description": "Fund the agent's own Polymarket Deposit Wallet: one exact USDC or USDT debit, or that many dollars of a coin, delivered as native Base USDC to Polymarket's bridge, which credits an estimated, not guaranteed, pUSD amount on Polygon later." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "SolanaFundContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_fund", "description": "Which authorization contract this is." }, "fund": { "description": "The exact approved amount and loss bound, and, for a funding paid with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaFundInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "fund", "maxExecutions", "validUntil" ], "description": "An approved move of USDC or USDT, or a coin, into the agent's own Solana account." }, "SolanaFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to move from the agent wallet into the agent's Solana account as SOL, in six-decimal atomic units: 5 USDC is \"5000000\". Spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." }, "payWith": { "description": "Approved in chat as one call: the coin this funding pays with instead of a USDC or USDT holding, and the most of it it may spend. Never SOL.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "Move an exact amount of USDC or USDT, or that many dollars of a coin, from the agent wallet into its own Solana account as SOL." }, "SolanaWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_withdraw", "description": "Which authorization contract this is." }, "withdraw": { "description": "The exact approved amount, what returns and the loss bound.", "$ref": "#/components/schemas/SolanaWithdrawInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "withdraw", "maxExecutions", "validUntil" ], "description": "An approved move of SOL from the agent's own Solana account back to its agent wallet." }, "SolanaWithdrawInput": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Withdraw an exact amount of SOL." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to withdraw, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Withdraw an exact amount of SOL." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_spendable", "description": "Withdraw all the SOL above the reserve the account keeps for rent and network fees." } }, "required": [ "kind" ], "description": "Withdraw all the spendable SOL." } ], "description": "How much SOL to withdraw from the agent's Solana account." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns it to the agent wallet as USDC on NEAR; `sol` returns it to the agent wallet as SOL." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." } }, "required": [ "amount", "receive", "maxValueLossBps" ], "description": "Move SOL from the agent's own Solana account back to its agent wallet." }, "PredictionOrderContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_order" }, "order": { "$ref": "#/components/schemas/PredictionOrderInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "order", "validUntil" ] }, "PredictionOrderInput": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$" }, "assetId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$" }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256 }, "side": { "type": "string", "enum": [ "BUY", "SELL" ] }, "limitPriceUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "shares" }, "sizeSharesDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "sizeSharesDecimal" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "budget" }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "kind", "amountUsdDecimal" ] } ] }, "orderType": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK" ] }, "expiresAt": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" }, "maxSpendUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})(\\.[0-9]{1,6})?$" } }, "required": [ "marketId", "assetId", "marketQuestion", "outcome", "side", "limitPriceUsdDecimal", "quantity", "orderType", "maxFeeUsdDecimal", "maxSpendUsdDecimal" ] }, "PredictionWithdrawContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_withdraw" }, "withdrawal": { "$ref": "#/components/schemas/PredictionWithdrawInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ] }, "PredictionWithdrawInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact pUSD debit in six-decimal atomic units: 5 pUSD is \"5000000\". Only the agent’s own Deposit Wallet is spent." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "amountRaw", "maxLossBps" ], "description": "Withdraw pUSD through Polymarket’s conversion service as native USDC on Polygon to a unique verified 1Click address crediting only the agent’s own confidential Intents wallet. Funding remains a separate USDC route." }, "CompositeContract": { "type": "object", "properties": { "type": { "type": "string", "const": "composite", "description": "Which authorization contract this is." }, "pieces": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "enum": [ "intents_execute", "perps_fund", "perps_order_place", "prediction_fund", "prediction_order_place", "perps_withdraw", "prediction_withdraw" ], "description": "The tool whose one-shot call this piece is." }, "contract": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ] }, "startBy": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "tool", "contract", "startBy" ] } }, "dependencies": { "type": "array", "items": { "maxItems": 6, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "walletDebit": { "anyOf": [ { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, { "type": "array", "prefixItems": [], "items": false, "maxItems": 0 } ], "description": "The sum of every piece's debit from the agent wallet, per token, in raw units. Empty when the pieces are venue orders paid from money already on their venues, as when finishing a basket, or a cash-out, which closes a position and brings home what that freed." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When every piece that has not started loses its authority." } }, "required": [ "type", "pieces", "dependencies", "walletDebit", "validUntil" ], "description": "One owner signature over several exact one-shot grants and the order they run in." }, "PerpsFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_freed_withdrawal", "description": "Which authorization contract this is." }, "withdrawal": { "description": "The signed maximum and all-in loss bound of the withdrawal home.", "$ref": "#/components/schemas/PerpsFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this one-shot approval authorizes nothing." } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's exit freed on Hyperliquid, at most the signed maximum. Only ever a piece of a cash-out." }, "PerpsFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic USDC: what the exit before it frees, sized by the host before the approval opens. Never more than the exit freed." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." } }, "required": [ "upToRaw", "maxValueLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the exit before it freed on its own Hyperliquid account, never more than upToRaw." }, "PredictionFreedWithdrawalContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_freed_withdrawal" }, "withdrawal": { "$ref": "#/components/schemas/PredictionFreedWithdrawalInput" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "type", "withdrawal", "validUntil" ], "description": "One withdrawal home of what a cash-out's sale freed on Polymarket, at most the signed maximum. Only ever a piece of a cash-out." }, "PredictionFreedWithdrawalInput": { "type": "object", "properties": { "upToRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this withdrawal may move, in six-decimal atomic pUSD: what the sale before it frees, sized by the host before the approval opens. Never more than the sale freed." }, "maxLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum estimated route loss in basis points, fees included; required, never defaulted. The bridge quote is an estimate, not a guaranteed final credit." } }, "required": [ "upToRaw", "maxLossBps" ], "description": "Withdraw to the agent's own confidential Intents wallet what the sale before it freed in its own Polymarket Deposit Wallet, never more than upToRaw." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaSellManyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell_many", "description": "Which authorization contract this is." }, "sellMany": { "description": "The exact approved coins, amounts and loss bounds, in order, and where the proceeds go.", "$ref": "#/components/schemas/SolanaSellManyInput" }, "maxExecutions": { "type": "number", "const": 1, "description": "A multi-coin sale is approved once and runs once: always 1." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sellMany", "maxExecutions", "validUntil" ], "description": "An approved multi-coin Solana sale, executed only exactly as approved." }, "SolanaSellManyInput": { "type": "object", "properties": { "sells": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/SolanaSale" }, "description": "The coins to sell, in the order they are sold: 2 to 6, each a different mint, none of them SOL itself." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the summed proceeds of every sale that went through to the agent wallet as USDC on NEAR, in one transfer once the last sale ran; `sol` keeps them as SOL in the agent's Solana account." } }, "required": [ "sells", "receive" ], "description": "Several sells of Solana tokens held in the agent's own Solana account, approved together and run as one: each sale on its own, one after another, then one transfer of what they returned." }, "SolanaSale": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "maxValueLossBps" ], "description": "One coin of a multi-coin sale, sold through the agent's own Solana account." }, "GridContract": { "type": "object", "properties": { "type": { "type": "string", "const": "grid", "description": "Which contract template this is." }, "grid": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "A grid's exact terms: pair, levels, quantity and starting sides." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends: no order is placed, and none rests, after it. At most 720 hours after the approval's own expiry." } }, "required": [ "type", "grid", "validUntil" ], "description": "Owner-signed authority for one grid: the resting cell orders its terms derive, until it ends." }, "ApprovalAuthorization": { "type": "object", "properties": { "purpose": { "type": "string", "const": "financial.approval", "description": "Always `financial.approval`: the signature approves this one money action." }, "walletId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet the action spends from." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id, which the signature names, so it approves this approval and no other." }, "request": { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval being decided." }, "fingerprint": { "type": "string", "description": "Fingerprint of the immutable approval bytes." }, "tool": { "type": "string", "description": "The exact trusted tool receiving the approved terms." }, "input": { "description": "The complete persisted tool arguments to approve.", "$ref": "#/components/schemas/JsonValue" }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ], "description": "Exact financial actions, quantity, allowance, validity and loss bounds authorized by this approval: swap actions, one limit order, one perps transfer/order/cancellation or margin change, one Polymarket funding/order/withdrawal, the exact Solana actions, or one grid's terms." }, "policy": { "description": "The custody worker's exact grant for these terms; clients sign it without mutation.", "$ref": "#/components/schemas/PolicyApprovalMessage" } }, "required": [ "approvalId", "fingerprint", "tool", "input", "contract", "policy" ], "description": "The exact terms the signature covers, including the permission they grant. Shown for review; the signed `message` already contains them." }, "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "purpose", "walletId", "requestKey", "request", "message", "controllerId", "expiresAt" ], "description": "What the user signs to approve a money action. Sign `message` exactly as returned and send the signature to Approve an action with `controllerId` and `expiresAt` unchanged." }, "PolicyApprovalMessage": { "type": "object", "properties": { "domain": { "type": "string", "const": "fin.policy.contract.v1", "description": "Domain separation for this signed policy message." }, "binding": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "testnet", "mainnet" ], "description": "The NEAR network this policy deployment serves." }, "project_uuid": { "type": "string", "minLength": 1, "description": "Stable policy deployment identifier." }, "caller_id": { "type": "string", "minLength": 1, "description": "Fin integration identity bound into consent." } }, "required": [ "network", "project_uuid", "caller_id" ], "description": "The deployment and caller to which this consent applies." }, "owner_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the canonical owner descriptor." }, "wallet_id": { "type": "string", "minLength": 1, "description": "The policy worker's wallet identity receiving this grant; the worker spends only from that wallet's own account." }, "approval_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The exact persisted approval to which this owner-signed grant belongs." }, "nonce": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Unique consent nonce; replay cannot create additional allowance." }, "issued_at_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Consent issue time in Unix milliseconds." }, "source": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "one_shot", "description": "One approved request, executed by the run that asked for it." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "grid", "description": "A standing grid grant: the cell orders its terms derive, placed by the grid engine without a run." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "automation", "description": "A standing grant that the named automation's recorded firings may exercise." }, "definition": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name, as approved." }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "The automation's saved prompt, as approved." }, "rule": { "$ref": "#/components/schemas/AutomationRule" } }, "required": [ "name", "prompt", "rule" ], "description": "The automation's exact saved definition; any edit invalidates this consent." }, "maxSigningDelaySeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "The owner-approved time after the worker records a firing during which its run may obtain signatures." }, "automationId": { "description": "The saved automation whose edited terms the owner approves; absent for creation.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "definitionVersion": { "description": "The saved definition version those edited terms authorize; absent for creation.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "kind", "definition", "maxSigningDelaySeconds" ] } ], "description": "What this consent authorizes: one present-user request, the firings of one exact automation, or one grid's derived orders." }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/LimitOrderContract" }, { "$ref": "#/components/schemas/PerpsTransferContract" }, { "$ref": "#/components/schemas/PerpsOrderContract" }, { "$ref": "#/components/schemas/PerpsCancelContract" }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PerpsMarginContract" }, { "$ref": "#/components/schemas/PredictionFundContract" }, { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" }, { "$ref": "#/components/schemas/SolanaFundContract" }, { "$ref": "#/components/schemas/SolanaWithdrawContract" }, { "$ref": "#/components/schemas/PredictionOrderContract" }, { "$ref": "#/components/schemas/PredictionWithdrawContract" }, { "$ref": "#/components/schemas/CompositeContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "$ref": "#/components/schemas/SolanaSellManyContract" }, { "$ref": "#/components/schemas/GridContract" }, { "$ref": "#/components/schemas/PerpsFreedWithdrawalContract" }, { "$ref": "#/components/schemas/PredictionFreedWithdrawalContract" } ], "description": "The exact approved authority: swap actions with their bounds, count and expiry, one limit order, one perps transfer/order/cancellation or margin change, one Polymarket funding/order/withdrawal, the exact Solana actions, or one grid." } }, "required": [ "domain", "binding", "owner_id", "wallet_id", "approval_id", "nonce", "issued_at_ms", "source", "contract" ], "description": "Owner-signed authority for one exact financial contract." }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ] } }, "required": [ "intervalSeconds", "readers" ] }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ] }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get the agent wallet 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. `GET /v1/users/{userId}/wallet` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The agent wallet, or the message that creates it. ```json { "description": "The agent wallet, or the message that creates it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "anyOf": [ { "$ref": "#/components/schemas/Wallet" }, { "type": "null" } ], "description": "The user's agent wallet, or `null` until the user creates it." }, "creation": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "While `wallet` is `null`: the message the user signs to create the wallet (Create the agent wallet). `null` once the wallet exists." }, "confirmation": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "For an existing wallet whose ownership has not been confirmed: the exact message its owner signs for Confirm wallet ownership. It names the existing wallet and account and grants no spending permission. Otherwise null." } }, "required": [ "wallet", "creation", "confirmation" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead ```json { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.get", "summary": "Get the agent wallet", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The agent wallet, or the message that creates it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "anyOf": [ { "$ref": "#/components/schemas/Wallet" }, { "type": "null" } ], "description": "The user's agent wallet, or `null` until the user creates it." }, "creation": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "While `wallet` is `null`: the message the user signs to create the wallet (Create the agent wallet). `null` once the wallet exists." }, "confirmation": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "For an existing wallet whose ownership has not been confirmed: the exact message its owner signs for Confirm wallet ownership. It names the existing wallet and account and grants no spending permission. Otherwise null." } }, "required": [ "wallet", "creation", "confirmation" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "Wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccountId": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The wallet's NEAR Intents account, as 64 lowercase hex characters: the account 1Click knows it by. You need it only to read the wallet from 1Click yourself (see Get a 1Click session)." }, "intentsAccount": { "description": "The same account with its kind. Here always `near`, with the same id as `intentsAccountId`: an Agent API wallet is read through Get wallet account.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation. Verify the version-specific signed message against your independently pinned worker key and compare the wallet and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccountId", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "MessageToSign": { "type": "object", "properties": { "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "message", "controllerId", "expiresAt" ], "description": "A message for the user to sign with their registered wallet or passkey, and the values to send back with the signature." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Create the agent wallet 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. `POST /v1/users/{userId}/wallet` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{}' ``` ## Responses ### 200 The agent wallet. ```json { "description": "The agent wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `signature_required` — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization` ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `signature_required` — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead ```json { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.create", "summary": "Create the agent wallet", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The agent wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `signature_required` — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "CreateWalletInput": { "type": "object", "properties": { "authorization": { "description": "The user's signature of `creation.message` from Get the agent wallet. Required when the user has no wallet yet, unless you send `signIn`, or send neither from the session that opened the account with a new passkey (Create a session answered `createsWallet: true`); not read once the wallet exists.", "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false }, "signIn": { "description": "Instead of `authorization`: the user's account-opening sign-in, from a challenge Start wallet sign-in answered with `createsWallet: true`. Send it within that challenge's five minutes; the user signs nothing more.", "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `challengeId` of the sign-in that opened this session." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The same signature you sent to Create a session for that challenge." } }, "required": [ "challengeId", "signature" ], "additionalProperties": false } }, "additionalProperties": false, "description": "The user's signature that creates their agent wallet." }, "Wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccountId": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The wallet's NEAR Intents account, as 64 lowercase hex characters: the account 1Click knows it by. You need it only to read the wallet from 1Click yourself (see Get a 1Click session)." }, "intentsAccount": { "description": "The same account with its kind. Here always `near`, with the same id as `intentsAccountId`: an Agent API wallet is read through Get wallet account.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation. Verify the version-specific signed message against your independently pinned worker key and compare the wallet and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccountId", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Confirm wallet ownership 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. `POST /v1/users/{userId}/wallet/confirm` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmWalletInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/confirm' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The same wallet with its ownership receipt. ```json { "description": "The same wallet with its ownership receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead ```json { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.confirm", "summary": "Confirm wallet ownership", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmWalletInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The same wallet with its ownership receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "ConfirmWalletInput": { "type": "object", "properties": { "authorization": { "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false, "description": "The user's signature of confirmation.message from Get the agent wallet, unchanged." } }, "required": [ "authorization" ], "additionalProperties": false, "description": "The owner's confirmation of their existing agent wallet." }, "Wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccountId": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The wallet's NEAR Intents account, as 64 lowercase hex characters: the account 1Click knows it by. You need it only to read the wallet from 1Click yourself (see Get a 1Click session)." }, "intentsAccount": { "description": "The same account with its kind. Here always `near`, with the same id as `intentsAccountId`: an Agent API wallet is read through Get wallet account.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation. Verify the version-specific signed message against your independently pinned worker key and compare the wallet and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccountId", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get wallet account 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 /v1/users/{userId}/wallet/account` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/account' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The agent wallet, or the message that creates it. ```json { "description": "The agent wallet, or the message that creates it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "anyOf": [ { "$ref": "#/components/schemas/AccountWallet" }, { "type": "null" } ], "description": "The user's agent wallet, or `null` until the user creates it." }, "creation": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "While `wallet` is `null`: the message the user signs to create the wallet (Start wallet setup, or Create the agent wallet). `null` once the wallet exists." }, "confirmation": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "For an existing wallet whose ownership has not been confirmed: the exact message its owner signs for Confirm wallet ownership. It names the existing wallet and account and grants no spending permission. Otherwise null." }, "renewal": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "For an active Agent API wallet (`intentsAccount.kind` is `evm`): the message its owner signs for Renew wallet access, when the agent's access is about to run out or was lost. Otherwise null." } }, "required": [ "wallet", "creation", "confirmation", "renewal" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getAccount", "summary": "Get wallet account", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The agent wallet, or the message that creates it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "anyOf": [ { "$ref": "#/components/schemas/AccountWallet" }, { "type": "null" } ], "description": "The user's agent wallet, or `null` until the user creates it." }, "creation": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "While `wallet` is `null`: the message the user signs to create the wallet (Start wallet setup, or Create the agent wallet). `null` once the wallet exists." }, "confirmation": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "For an existing wallet whose ownership has not been confirmed: the exact message its owner signs for Confirm wallet ownership. It names the existing wallet and account and grants no spending permission. Otherwise null." }, "renewal": { "anyOf": [ { "$ref": "#/components/schemas/MessageToSign" }, { "type": "null" } ], "description": "For an active Agent API wallet (`intentsAccount.kind` is `evm`): the message its owner signs for Renew wallet access, when the agent's access is about to run out or was lost. Otherwise null." } }, "required": [ "wallet", "creation", "confirmation", "renewal" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "AccountWallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccount": { "description": "The wallet's NEAR Intents account and its kind: `near` for a Fin-held wallet, `evm` for an Agent API wallet.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation; version 3 with basis agent_api proves the owner signed an Agent API wallet's creation and names its `intentsAccount`. Verify the version-specific signed message against your independently pinned worker key and compare the wallet, account and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet, whatever its kind: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "MessageToSign": { "type": "object", "properties": { "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "message", "controllerId", "expiresAt" ], "description": "A message for the user to sign with their registered wallet or passkey, and the values to send back with the signature." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get wallet account balances 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`. `GET /v1/users/{userId}/wallet/account/balances` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/account/balances' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The agent wallet and what it holds. ```json { "description": "The agent wallet and what it holds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWalletBalances" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getAccountBalances", "summary": "Get wallet account balances", "tags": [ "wallets" ], "description": "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`.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The agent wallet and what it holds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWalletBalances" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "AccountWalletBalances": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/AccountWallet" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The asset's ticker symbol, as the provider reports it." }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's display name, as the provider reports it." }, "decimals": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 255 }, { "type": "null" } ], "description": "How many decimal places `amountRaw` carries; `null` if the provider does not name this asset." }, "amountRaw": { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$", "description": "The held amount, as a decimal string in the asset's smallest unit, never a float; scale by `decimals` for a human amount." }, "priceUsdDecimal": { "anyOf": [ { "type": "string", "maxLength": 500, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The asset's price in USD, as a decimal string, never a float; `null` if the provider has no price for it." }, "valueUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "This holding's value, in US cents as a decimal integer string, never a float; `null` if `priceUsdDecimal` is `null`." }, "iconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "An https icon for the asset, or `null` if the provider has none." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "transferAsset": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ] }, { "type": "null" } ], "description": "The asset as deposits and withdrawals name it; null when it is not a supported asset." } }, "required": [ "symbol", "name", "decimals", "amountRaw", "priceUsdDecimal", "valueUsdCents", "iconUrl", "assetId", "transferAsset" ] }, "description": "Each asset the wallet holds, with its exact amount in the asset's smallest unit." }, "totalUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The sum of every priced asset's value, in US cents as a decimal integer string, never a float; `null` if any asset's price is unknown." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this snapshot was read from the provider." }, "portfolio": { "$ref": "#/components/schemas/WalletPortfolioSummary" }, "depositLimit": { "anyOf": [ { "type": "object", "properties": { "maxWalletValueCents": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})$", "description": "The most the agent wallet may be worth with a deposit added, in US cents: its value, the deposits still under way and the new one." }, "availableCents": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})$", "description": "How much more can be deposited right now, in US cents: the limit less the wallet's value and the deposits still under way, and 0 when the wallet is at or over its limit. A deposit worth more is refused with `deposit_limit_exceeded`, and so is a deposit address once this is 0." } }, "required": [ "maxWalletValueCents", "availableCents" ] }, { "type": "null" } ], "description": "The user's deposit limit, or null when none applies. Use `availableCents` to say how much the user can deposit before asking for an address; Create a deposit and Create a deposit address check it again." } }, "required": [ "wallet", "assets", "totalUsdCents", "asOf", "portfolio", "depositLimit" ], "description": "The agent wallet, whatever its kind, what it holds right now, and how much more it can take." }, "AccountWallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccount": { "description": "The wallet's NEAR Intents account and its kind: `near` for a Fin-held wallet, `evm` for an Agent API wallet.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation; version 3 with basis agent_api proves the owner signed an Agent API wallet's creation and names its `intentsAccount`. Verify the version-specific signed message against your independently pinned worker key and compare the wallet, account and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet, whatever its kind: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "WalletPortfolioSummary": { "type": "object", "properties": { "availableUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The available wallet balance, identical to `totalUsdCents` outside this summary; null if any held asset is unpriced." }, "inOrdersUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The value of the funds resting in the user's open limit orders, at current prices. Null when an order's report is missing, more than 10 minutes old or unpriced." }, "incomingUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The value of order payouts on their way to the wallet: a filled order's output or a cancelled order's refund, at the amount the order provider reports, before any settlement fee. Zero when nothing is on its way. Once a payout completes, it is part of the available balance instead." }, "totalUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The account's value: available plus in orders plus incoming. Null while any part is unknown; `reasons` says which." }, "pricedSubtotalUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The sum of priced available-wallet assets only, even when another wallet asset is unpriced. Excludes all order allocations and incoming funds; not a portfolio total. Null if the exact sum exceeds the supported cent-string range." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the available wallet balance was observed." }, "complete": { "type": "boolean", "description": "Whether `totalUsdCents` is known. The total excludes positions held in separate Earn or perps accounts." }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "unpriced_wallet_assets", "order_allocation_unknown", "order_prices_unavailable", "order_settlement_unreconciled", "orders_unavailable", "order_observation_stale", "valuation_out_of_range" ] }, "description": "Why the total is unknown; an empty list means it is known. `order_settlement_unreconciled`: an order's payout failed, or only some of its fills have been paid out, so what is still to come has no amount. `order_allocation_unknown`: an order's amounts aren't reported yet, or a funded order's deposit hasn't been seen yet. `order_observation_stale`: an order holding funds hasn't been read for over 10 minutes." }, "hasAssets": { "description": "True when the wallet holds a positive balance or an order holds or is paying back funds, false only when both are known empty, and null when an order's funds cannot be established. Use false for an empty-state screen; a zero USD value alone does not mean empty.", "type": [ "boolean", "null" ] } }, "required": [ "availableUsdCents", "inOrdersUsdCents", "incomingUsdCents", "totalUsdCents", "pricedSubtotalUsdCents", "asOf", "complete", "reasons", "hasAssets" ], "description": "The account's value: available wallet cash, funds in open orders and order payouts on their way, and their total." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Open a wallet account session 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. `POST /v1/users/{userId}/wallet/account/sessions` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/account/sessions' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A new 1Click session for the agent wallet. ```json { "description": "A new 1Click session for the agent wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWalletSession" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.openAccountSession", "summary": "Open a wallet account session", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A new 1Click session for the agent wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountWalletSession" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "AccountWalletSession": { "type": "object", "properties": { "intentsAccount": { "description": "The agent wallet's NEAR Intents account and its kind: the account these tokens sign in as, and the `account_id` inside them.", "$ref": "#/components/schemas/IntentsAccount" }, "accessToken": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "A 1Click access token for the agent wallet. Send it as `Authorization: Bearer` to 1Click's account endpoints, such as balances and history." }, "accessTokenExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the access token expires. Then exchange `refreshToken` for a new one at 1Click's `POST /v0/auth/refresh`, as you do for your own users." }, "refreshToken": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Exchanges for new access tokens at 1Click until `refreshTokenExpiresAt`. 1Click answers a refresh with a new access token only, so keep this one." }, "refreshTokenExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the refresh token expires. After that, or when 1Click refuses it, get a new session." } }, "required": [ "intentsAccount", "accessToken", "accessTokenExpiresAt", "refreshToken", "refreshTokenExpiresAt" ], "description": "A 1Click session for the agent wallet, whatever its kind, so your backend can read it from 1Click with its own code." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Start wallet setup 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`. `POST /v1/users/{userId}/wallet/setup` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/setup' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{}' ``` ## Responses ### 200 The next step the user signs, or the wallet. ```json { "description": "The next step the user signs, or the wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSetup" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `signature_required` — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization` ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `signature_required` — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `policy_change_throttled` — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `policy_change_throttled` — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.startSetup", "summary": "Start wallet setup", "tags": [ "wallets" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The next step the user signs, or the wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSetup" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `signature_required` — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `policy_change_throttled` — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "CreateWalletInput": { "type": "object", "properties": { "authorization": { "description": "The user's signature of `creation.message` from Get the agent wallet. Required when the user has no wallet yet, unless you send `signIn`, or send neither from the session that opened the account with a new passkey (Create a session answered `createsWallet: true`); not read once the wallet exists.", "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false }, "signIn": { "description": "Instead of `authorization`: the user's account-opening sign-in, from a challenge Start wallet sign-in answered with `createsWallet: true`. Send it within that challenge's five minutes; the user signs nothing more.", "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `challengeId` of the sign-in that opened this session." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The same signature you sent to Create a session for that challenge." } }, "required": [ "challengeId", "signature" ], "additionalProperties": false } }, "additionalProperties": false, "description": "The user's signature that creates their agent wallet." }, "WalletSetup": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "signature_required", "completed" ], "description": "`signature_required`: the user signs `step.intent`, then send it to Continue wallet setup. `completed`: `wallet` is ready." }, "step": { "anyOf": [ { "type": "object", "properties": { "setupId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "This step's id: send it back to Continue wallet setup with the signature." }, "step": { "type": "string", "enum": [ "agent_create", "policy_update", "grant_issue", "grant_revoke" ], "description": "`agent_create`: the user creates their agent account, which they own. `grant_issue`: the user lets Fin's agent sign with it for a year; in public-key mode the summary names the signing key's thumbprint, not a token fingerprint. `grant_revoke`: after renewal, the user revokes the retired token grant. `policy_update`: the user enables limit orders through Start wallet setup, or lets their agent account pay one more address through Add a withdrawal destination." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When this step can no longer be signed. After it, Start wallet setup or Renew wallet access again for a fresh one." }, "summary": { "type": "string", "maxLength": 4096, "description": "What the user agrees to, in the Agent API's words: show it before they sign." }, "intent": { "$ref": "#/components/schemas/WalletSetupIntent" }, "policy": { "description": "For `agent_create` and `policy_update`: what the user's agent account may do once they sign, as Fin asked the Agent API for it (for `policy_update`, everything it allows after the change). Show it beside `summary`. Absent for `grant_issue`, and when Fin cannot state it for this step.", "type": "object", "properties": { "limitOrder": { "type": "boolean", "description": "Whether the agent account can place confidential limit orders at market or better, with no price deviation allowed below market." }, "maxSlippageBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "The most of its value a swap or payout the agent account signs may lose in total, in basis points (300 is 3%): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output." }, "destinations": { "maxItems": 512, "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "maxLength": 64, "description": "The network the address is on: `near-intents-confidential` for a NEAR Intents account, otherwise a network `id` such as `eth` or `near`." }, "address": { "type": "string", "maxLength": 256, "description": "The address, as the agent account lists it." }, "venue": { "description": "When the address is the agent's own account on a venue, which one: `perps` its Hyperliquid account, `prediction` the Polymarket bridge's deposit address for its Polymarket account, `solana` its Solana account. Fin derived it, so show it as funding the user's own account there, not as a payout. Absent for any other address.", "type": "string", "enum": [ "perps", "prediction", "solana" ] } }, "required": [ "network", "address" ] }, "description": "Every address the agent account may pay, and nothing else." } }, "required": [ "limitOrder", "maxSlippageBps", "destinations" ] }, "accessExpiresAt": { "description": "For `grant_issue`: when the access the user gives Fin's agent ends, unless they renew it sooner (Renew wallet access). Absent for the other steps, and when Fin cannot state it for this step.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "setupId", "step", "expiresAt", "summary", "intent" ] }, { "type": "null" } ], "description": "While `signature_required`: what the user signs next. Otherwise null." }, "wallet": { "anyOf": [ { "$ref": "#/components/schemas/AccountWallet" }, { "type": "null" } ], "description": "Once `completed`: the agent wallet. Otherwise null." } }, "required": [ "status", "step", "wallet" ], "description": "Where setting up the agent wallet stands: the next step the user signs, or the wallet." }, "WalletSetupIntent": { "type": "object", "properties": { "standard": { "type": "string", "enum": [ "nep366", "nep413", "eip712", "webauthn" ], "description": "How the user's wallet signs `payload`: `nep366` a NEAR delegate action (`signDelegateActions`), `nep413` a NEAR message (`signMessage`, with `nonce` decoded from base64 to its 32 bytes), `eip712` EVM typed data (`signTypedData`), `webauthn` a passkey assertion (`navigator.credentials.get` with `payload` as its request options)." }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "What the user's wallet signs, exactly as given: never rebuild, reorder or hash it." } }, "required": [ "standard", "payload" ], "description": "What the user's wallet or passkey signs for one wallet setup step." }, "AccountWallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccount": { "description": "The wallet's NEAR Intents account and its kind: `near` for a Fin-held wallet, `evm` for an Agent API wallet.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation; version 3 with basis agent_api proves the owner signed an Agent API wallet's creation and names its `intentsAccount`. Verify the version-specific signed message against your independently pinned worker key and compare the wallet, account and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet, whatever its kind: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Continue wallet setup 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. `POST /v1/users/{userId}/wallet/setup/continue` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContinueWalletSetupInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/setup/continue' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The next step the user signs, or the wallet. ```json { "description": "The next step the user signs, or the wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSetup" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.continueSetup", "summary": "Continue wallet setup", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContinueWalletSetupInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The next step the user signs, or the wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSetup" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "ContinueWalletSetupInput": { "type": "object", "properties": { "setupId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The `step.setupId` the user signed." }, "signature": { "$ref": "#/components/schemas/WalletSetupSignatureInput" } }, "required": [ "setupId", "signature" ], "additionalProperties": false, "description": "The user's signature of one wallet setup step." }, "WalletSetupSignatureInput": { "oneOf": [ { "type": "object", "properties": { "standard": { "type": "string", "const": "nep366" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The `intent.payload` the user signed, unchanged." }, "signed_delegate": { "type": "string", "minLength": 1, "maxLength": 16384, "pattern": "^[A-Za-z0-9+/]+={0,2}$", "description": "The signed delegate action the NEAR wallet answered (`signedDelegateActions[0]`), base64." } }, "required": [ "standard", "payload", "signed_delegate" ], "additionalProperties": false }, { "type": "object", "properties": { "standard": { "type": "string", "const": "nep413" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The `intent.payload` the user signed, unchanged." }, "public_key": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The key that signed, as the NEAR wallet reports it." }, "signature": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The signature the NEAR wallet answered, as it answered it." } }, "required": [ "standard", "payload", "public_key", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "standard": { "type": "string", "const": "eip712" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The `intent.payload` the user signed, unchanged." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte typed-data signature the EVM wallet answered." } }, "required": [ "standard", "payload", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "standard": { "type": "string", "const": "webauthn" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The `intent.payload` the user signed, unchanged." }, "credential": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, "rawId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, "type": { "type": "string", "const": "public-key" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, "userHandle": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, "clientExtensionResults": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "authenticatorAttachment": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] } }, "required": [ "id", "rawId", "type", "response", "clientExtensionResults" ], "additionalProperties": false, "description": "The passkey assertion, as `startAuthentication` answers it (JSON-encoded)." } }, "required": [ "standard", "payload", "credential" ], "additionalProperties": false } ], "description": "The setup step's `intent` with the user's wallet output added: `signed_delegate` for `nep366`, `public_key` and `signature` for `nep413`, `signature` for `eip712`, `credential` for `webauthn`." }, "WalletSetup": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "signature_required", "completed" ], "description": "`signature_required`: the user signs `step.intent`, then send it to Continue wallet setup. `completed`: `wallet` is ready." }, "step": { "anyOf": [ { "type": "object", "properties": { "setupId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "This step's id: send it back to Continue wallet setup with the signature." }, "step": { "type": "string", "enum": [ "agent_create", "policy_update", "grant_issue", "grant_revoke" ], "description": "`agent_create`: the user creates their agent account, which they own. `grant_issue`: the user lets Fin's agent sign with it for a year; in public-key mode the summary names the signing key's thumbprint, not a token fingerprint. `grant_revoke`: after renewal, the user revokes the retired token grant. `policy_update`: the user enables limit orders through Start wallet setup, or lets their agent account pay one more address through Add a withdrawal destination." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When this step can no longer be signed. After it, Start wallet setup or Renew wallet access again for a fresh one." }, "summary": { "type": "string", "maxLength": 4096, "description": "What the user agrees to, in the Agent API's words: show it before they sign." }, "intent": { "$ref": "#/components/schemas/WalletSetupIntent" }, "policy": { "description": "For `agent_create` and `policy_update`: what the user's agent account may do once they sign, as Fin asked the Agent API for it (for `policy_update`, everything it allows after the change). Show it beside `summary`. Absent for `grant_issue`, and when Fin cannot state it for this step.", "type": "object", "properties": { "limitOrder": { "type": "boolean", "description": "Whether the agent account can place confidential limit orders at market or better, with no price deviation allowed below market." }, "maxSlippageBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "The most of its value a swap or payout the agent account signs may lose in total, in basis points (300 is 3%): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output." }, "destinations": { "maxItems": 512, "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "maxLength": 64, "description": "The network the address is on: `near-intents-confidential` for a NEAR Intents account, otherwise a network `id` such as `eth` or `near`." }, "address": { "type": "string", "maxLength": 256, "description": "The address, as the agent account lists it." }, "venue": { "description": "When the address is the agent's own account on a venue, which one: `perps` its Hyperliquid account, `prediction` the Polymarket bridge's deposit address for its Polymarket account, `solana` its Solana account. Fin derived it, so show it as funding the user's own account there, not as a payout. Absent for any other address.", "type": "string", "enum": [ "perps", "prediction", "solana" ] } }, "required": [ "network", "address" ] }, "description": "Every address the agent account may pay, and nothing else." } }, "required": [ "limitOrder", "maxSlippageBps", "destinations" ] }, "accessExpiresAt": { "description": "For `grant_issue`: when the access the user gives Fin's agent ends, unless they renew it sooner (Renew wallet access). Absent for the other steps, and when Fin cannot state it for this step.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "setupId", "step", "expiresAt", "summary", "intent" ] }, { "type": "null" } ], "description": "While `signature_required`: what the user signs next. Otherwise null." }, "wallet": { "anyOf": [ { "$ref": "#/components/schemas/AccountWallet" }, { "type": "null" } ], "description": "Once `completed`: the agent wallet. Otherwise null." } }, "required": [ "status", "step", "wallet" ], "description": "Where setting up the agent wallet stands: the next step the user signs, or the wallet." }, "WalletSetupIntent": { "type": "object", "properties": { "standard": { "type": "string", "enum": [ "nep366", "nep413", "eip712", "webauthn" ], "description": "How the user's wallet signs `payload`: `nep366` a NEAR delegate action (`signDelegateActions`), `nep413` a NEAR message (`signMessage`, with `nonce` decoded from base64 to its 32 bytes), `eip712` EVM typed data (`signTypedData`), `webauthn` a passkey assertion (`navigator.credentials.get` with `payload` as its request options)." }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "What the user's wallet signs, exactly as given: never rebuild, reorder or hash it." } }, "required": [ "standard", "payload" ], "description": "What the user's wallet or passkey signs for one wallet setup step." }, "AccountWallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccount": { "description": "The wallet's NEAR Intents account and its kind: `near` for a Fin-held wallet, `evm` for an Agent API wallet.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation; version 3 with basis agent_api proves the owner signed an Agent API wallet's creation and names its `intentsAccount`. Verify the version-specific signed message against your independently pinned worker key and compare the wallet, account and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet, whatever its kind: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Renew wallet access 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. `POST /v1/users/{userId}/wallet/access/renew` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewWalletAccessInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/access/renew' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The step the user signs to renew the access. ```json { "description": "The step the user signs to renew the access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSetup" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.renewAccess", "summary": "Renew wallet access", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewWalletAccessInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The step the user signs to renew the access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSetup" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "RenewWalletAccessInput": { "type": "object", "properties": { "authorization": { "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false, "description": "The user's signature of `renewal.message` from Get wallet account, unchanged." } }, "required": [ "authorization" ], "additionalProperties": false, "description": "The owner's request to renew the agent's access to their Agent API wallet." }, "WalletSetup": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "signature_required", "completed" ], "description": "`signature_required`: the user signs `step.intent`, then send it to Continue wallet setup. `completed`: `wallet` is ready." }, "step": { "anyOf": [ { "type": "object", "properties": { "setupId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "This step's id: send it back to Continue wallet setup with the signature." }, "step": { "type": "string", "enum": [ "agent_create", "policy_update", "grant_issue", "grant_revoke" ], "description": "`agent_create`: the user creates their agent account, which they own. `grant_issue`: the user lets Fin's agent sign with it for a year; in public-key mode the summary names the signing key's thumbprint, not a token fingerprint. `grant_revoke`: after renewal, the user revokes the retired token grant. `policy_update`: the user enables limit orders through Start wallet setup, or lets their agent account pay one more address through Add a withdrawal destination." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When this step can no longer be signed. After it, Start wallet setup or Renew wallet access again for a fresh one." }, "summary": { "type": "string", "maxLength": 4096, "description": "What the user agrees to, in the Agent API's words: show it before they sign." }, "intent": { "$ref": "#/components/schemas/WalletSetupIntent" }, "policy": { "description": "For `agent_create` and `policy_update`: what the user's agent account may do once they sign, as Fin asked the Agent API for it (for `policy_update`, everything it allows after the change). Show it beside `summary`. Absent for `grant_issue`, and when Fin cannot state it for this step.", "type": "object", "properties": { "limitOrder": { "type": "boolean", "description": "Whether the agent account can place confidential limit orders at market or better, with no price deviation allowed below market." }, "maxSlippageBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "The most of its value a swap or payout the agent account signs may lose in total, in basis points (300 is 3%): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output." }, "destinations": { "maxItems": 512, "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "maxLength": 64, "description": "The network the address is on: `near-intents-confidential` for a NEAR Intents account, otherwise a network `id` such as `eth` or `near`." }, "address": { "type": "string", "maxLength": 256, "description": "The address, as the agent account lists it." }, "venue": { "description": "When the address is the agent's own account on a venue, which one: `perps` its Hyperliquid account, `prediction` the Polymarket bridge's deposit address for its Polymarket account, `solana` its Solana account. Fin derived it, so show it as funding the user's own account there, not as a payout. Absent for any other address.", "type": "string", "enum": [ "perps", "prediction", "solana" ] } }, "required": [ "network", "address" ] }, "description": "Every address the agent account may pay, and nothing else." } }, "required": [ "limitOrder", "maxSlippageBps", "destinations" ] }, "accessExpiresAt": { "description": "For `grant_issue`: when the access the user gives Fin's agent ends, unless they renew it sooner (Renew wallet access). Absent for the other steps, and when Fin cannot state it for this step.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "setupId", "step", "expiresAt", "summary", "intent" ] }, { "type": "null" } ], "description": "While `signature_required`: what the user signs next. Otherwise null." }, "wallet": { "anyOf": [ { "$ref": "#/components/schemas/AccountWallet" }, { "type": "null" } ], "description": "Once `completed`: the agent wallet. Otherwise null." } }, "required": [ "status", "step", "wallet" ], "description": "Where setting up the agent wallet stands: the next step the user signs, or the wallet." }, "WalletSetupIntent": { "type": "object", "properties": { "standard": { "type": "string", "enum": [ "nep366", "nep413", "eip712", "webauthn" ], "description": "How the user's wallet signs `payload`: `nep366` a NEAR delegate action (`signDelegateActions`), `nep413` a NEAR message (`signMessage`, with `nonce` decoded from base64 to its 32 bytes), `eip712` EVM typed data (`signTypedData`), `webauthn` a passkey assertion (`navigator.credentials.get` with `payload` as its request options)." }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "What the user's wallet signs, exactly as given: never rebuild, reorder or hash it." } }, "required": [ "standard", "payload" ], "description": "What the user's wallet or passkey signs for one wallet setup step." }, "AccountWallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccount": { "description": "The wallet's NEAR Intents account and its kind: `near` for a Fin-held wallet, `evm` for an Agent API wallet.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation; version 3 with basis agent_api proves the owner signed an Agent API wallet's creation and names its `intentsAccount`. Verify the version-specific signed message against your independently pinned worker key and compare the wallet, account and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet, whatever its kind: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Add a withdrawal destination 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. `POST /v1/users/{userId}/wallet/destinations` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddWalletDestinationInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/destinations' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The step the user signs, or the wallet. ```json { "description": "The step the user signs, or the wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSetup" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `perps_disabled` — perps is not enabled for this user - `prediction_disabled` — prediction-market trading is not enabled for this user - `solana_disabled` — Solana trading is not enabled for this user ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `perps_disabled` — perps is not enabled for this user\n- `prediction_disabled` — prediction-market trading is not enabled for this user\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. - `no_account` — the user has not opened the account this call reads; open it first ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `policy_change_throttled` — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `policy_change_throttled` — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.addDestination", "summary": "Add a withdrawal destination", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddWalletDestinationInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The step the user signs, or the wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSetup" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `perps_disabled` — perps is not enabled for this user\n- `prediction_disabled` — prediction-market trading is not enabled for this user\n- `solana_disabled` — Solana trading is not enabled for this user", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `no_account` — the user has not opened the account this call reads; open it first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `policy_change_throttled` — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "AddWalletDestinationInput": { "anyOf": [ { "type": "object", "properties": { "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The blockchain the destination is on: a network `id` from List supported assets, such as `eth` or `near`." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "The destination's address on that network, exactly as withdrawals to it will name it." } }, "required": [ "network", "address" ], "additionalProperties": false }, { "type": "object", "properties": { "venue": { "type": "string", "enum": [ "perps", "prediction", "solana" ], "description": "A venue account of the agent's own that funding it pays: `perps` its Hyperliquid account, `prediction` the Polymarket bridge's deposit address for its Polymarket account, `solana` its Solana account. Fin names the exact address and chain the funding pays, opening the account first when it is new (`no_account` while a Polymarket account is still opening)." } }, "required": [ "venue" ], "additionalProperties": false } ], "description": "A place the user lets their Agent API wallet pay: an address on a network, or one of the agent's own venue accounts by its venue." }, "WalletSetup": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "signature_required", "completed" ], "description": "`signature_required`: the user signs `step.intent`, then send it to Continue wallet setup. `completed`: `wallet` is ready." }, "step": { "anyOf": [ { "type": "object", "properties": { "setupId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "This step's id: send it back to Continue wallet setup with the signature." }, "step": { "type": "string", "enum": [ "agent_create", "policy_update", "grant_issue", "grant_revoke" ], "description": "`agent_create`: the user creates their agent account, which they own. `grant_issue`: the user lets Fin's agent sign with it for a year; in public-key mode the summary names the signing key's thumbprint, not a token fingerprint. `grant_revoke`: after renewal, the user revokes the retired token grant. `policy_update`: the user enables limit orders through Start wallet setup, or lets their agent account pay one more address through Add a withdrawal destination." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When this step can no longer be signed. After it, Start wallet setup or Renew wallet access again for a fresh one." }, "summary": { "type": "string", "maxLength": 4096, "description": "What the user agrees to, in the Agent API's words: show it before they sign." }, "intent": { "$ref": "#/components/schemas/WalletSetupIntent" }, "policy": { "description": "For `agent_create` and `policy_update`: what the user's agent account may do once they sign, as Fin asked the Agent API for it (for `policy_update`, everything it allows after the change). Show it beside `summary`. Absent for `grant_issue`, and when Fin cannot state it for this step.", "type": "object", "properties": { "limitOrder": { "type": "boolean", "description": "Whether the agent account can place confidential limit orders at market or better, with no price deviation allowed below market." }, "maxSlippageBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "The most of its value a swap or payout the agent account signs may lose in total, in basis points (300 is 3%): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output." }, "destinations": { "maxItems": 512, "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "maxLength": 64, "description": "The network the address is on: `near-intents-confidential` for a NEAR Intents account, otherwise a network `id` such as `eth` or `near`." }, "address": { "type": "string", "maxLength": 256, "description": "The address, as the agent account lists it." }, "venue": { "description": "When the address is the agent's own account on a venue, which one: `perps` its Hyperliquid account, `prediction` the Polymarket bridge's deposit address for its Polymarket account, `solana` its Solana account. Fin derived it, so show it as funding the user's own account there, not as a payout. Absent for any other address.", "type": "string", "enum": [ "perps", "prediction", "solana" ] } }, "required": [ "network", "address" ] }, "description": "Every address the agent account may pay, and nothing else." } }, "required": [ "limitOrder", "maxSlippageBps", "destinations" ] }, "accessExpiresAt": { "description": "For `grant_issue`: when the access the user gives Fin's agent ends, unless they renew it sooner (Renew wallet access). Absent for the other steps, and when Fin cannot state it for this step.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "setupId", "step", "expiresAt", "summary", "intent" ] }, { "type": "null" } ], "description": "While `signature_required`: what the user signs next. Otherwise null." }, "wallet": { "anyOf": [ { "$ref": "#/components/schemas/AccountWallet" }, { "type": "null" } ], "description": "Once `completed`: the agent wallet. Otherwise null." } }, "required": [ "status", "step", "wallet" ], "description": "Where setting up the agent wallet stands: the next step the user signs, or the wallet." }, "WalletSetupIntent": { "type": "object", "properties": { "standard": { "type": "string", "enum": [ "nep366", "nep413", "eip712", "webauthn" ], "description": "How the user's wallet signs `payload`: `nep366` a NEAR delegate action (`signDelegateActions`), `nep413` a NEAR message (`signMessage`, with `nonce` decoded from base64 to its 32 bytes), `eip712` EVM typed data (`signTypedData`), `webauthn` a passkey assertion (`navigator.credentials.get` with `payload` as its request options)." }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "What the user's wallet signs, exactly as given: never rebuild, reorder or hash it." } }, "required": [ "standard", "payload" ], "description": "What the user's wallet or passkey signs for one wallet setup step." }, "AccountWallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccount": { "description": "The wallet's NEAR Intents account and its kind: `near` for a Fin-held wallet, `evm` for an Agent API wallet.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation; version 3 with basis agent_api proves the owner signed an Agent API wallet's creation and names its `intentsAccount`. Verify the version-specific signed message against your independently pinned worker key and compare the wallet, account and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet, whatever its kind: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a 1Click session 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. `POST /v1/users/{userId}/wallet/sessions` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/sessions' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A new 1Click session for the agent wallet. ```json { "description": "A new 1Click session for the agent wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSession" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead ```json { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.createSession", "summary": "Get a 1Click session", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A new 1Click session for the agent wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSession" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "WalletSession": { "type": "object", "properties": { "intentsAccountId": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The agent wallet's NEAR Intents account: the account these tokens sign in as, and the `account_id` inside them." }, "intentsAccount": { "description": "The same account with its kind. Here always `near`: an Agent API wallet's session comes from Open a wallet account session.", "$ref": "#/components/schemas/IntentsAccount" }, "accessToken": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "A 1Click access token for the agent wallet. Send it as `Authorization: Bearer` to 1Click's account endpoints, such as balances and history." }, "accessTokenExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the access token expires. Then exchange `refreshToken` for a new one at 1Click's `POST /v0/auth/refresh`, as you do for your own users." }, "refreshToken": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Exchanges for new access tokens at 1Click until `refreshTokenExpiresAt`. 1Click answers a refresh with a new access token only, so keep this one." }, "refreshTokenExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the refresh token expires. After that, or when 1Click refuses it, get a new session." } }, "required": [ "intentsAccountId", "intentsAccount", "accessToken", "accessTokenExpiresAt", "refreshToken", "refreshTokenExpiresAt" ], "description": "A 1Click session for the agent wallet, so your backend can read it from 1Click with its own code." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get balances 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 /v1/users/{userId}/wallet/balances` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/balances' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The agent wallet and what it holds. ```json { "description": "The agent wallet and what it holds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBalances" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead ```json { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.balances", "summary": "Get balances", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The agent wallet and what it holds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBalances" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `wallet_account_unsupported` — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "WalletBalances": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Wallet" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The asset's ticker symbol, as the provider reports it." }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's display name, as the provider reports it." }, "decimals": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 255 }, { "type": "null" } ], "description": "How many decimal places `amountRaw` carries; `null` if the provider does not name this asset." }, "amountRaw": { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$", "description": "The held amount, as a decimal string in the asset's smallest unit, never a float; scale by `decimals` for a human amount." }, "priceUsdDecimal": { "anyOf": [ { "type": "string", "maxLength": 500, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The asset's price in USD, as a decimal string, never a float; `null` if the provider has no price for it." }, "valueUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "This holding's value, in US cents as a decimal integer string, never a float; `null` if `priceUsdDecimal` is `null`." }, "iconUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "An https icon for the asset, or `null` if the provider has none." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "transferAsset": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ] }, { "type": "null" } ], "description": "The asset as deposits and withdrawals name it; null when it is not a supported asset." } }, "required": [ "symbol", "name", "decimals", "amountRaw", "priceUsdDecimal", "valueUsdCents", "iconUrl", "assetId", "transferAsset" ] }, "description": "Each asset the wallet holds, with its exact amount in the asset's smallest unit." }, "totalUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The sum of every priced asset's value, in US cents as a decimal integer string, never a float; `null` if any asset's price is unknown." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this snapshot was read from the provider." }, "portfolio": { "$ref": "#/components/schemas/WalletPortfolioSummary" }, "depositLimit": { "anyOf": [ { "type": "object", "properties": { "maxWalletValueCents": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})$", "description": "The most the agent wallet may be worth with a deposit added, in US cents: its value, the deposits still under way and the new one." }, "availableCents": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})$", "description": "How much more can be deposited right now, in US cents: the limit less the wallet's value and the deposits still under way, and 0 when the wallet is at or over its limit. A deposit worth more is refused with `deposit_limit_exceeded`, and so is a deposit address once this is 0." } }, "required": [ "maxWalletValueCents", "availableCents" ] }, { "type": "null" } ], "description": "The user's deposit limit, or null when none applies. Use `availableCents` to say how much the user can deposit before asking for an address; Create a deposit and Create a deposit address check it again." } }, "required": [ "wallet", "assets", "totalUsdCents", "asOf", "portfolio", "depositLimit" ], "description": "The agent wallet, what it holds right now, and how much more it can take." }, "Wallet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The agent wallet's id." }, "intentsAccountId": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The wallet's NEAR Intents account, as 64 lowercase hex characters: the account 1Click knows it by. You need it only to read the wallet from 1Click yourself (see Get a 1Click session)." }, "intentsAccount": { "description": "The same account with its kind. Here always `near`, with the same id as `intentsAccountId`: an Agent API wallet is read through Get wallet account.", "$ref": "#/components/schemas/IntentsAccount" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "`active`, or `disabled` once an operator has turned the wallet off." }, "provisionStatus": { "type": "string", "enum": [ "pending", "ready", "authorization_required" ], "description": "Whether the wallet can reach its provider: `pending` before its first connection, `ready` once connected, `authorization_required` after the provider refused its session. The server reconnects it on its own a few minutes later, on the next balance read or wallet activity; nothing is needed from the user." }, "ownership": { "anyOf": [ { "type": "object", "properties": { "statement": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "canonicalJson of the statement; the exact bytes the signature covers, minus the domain line." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The worker identity key's 64-byte Ed25519 signature in padded standard base64." }, "workerPublicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The worker identity key that signed, as ed25519:." } }, "required": [ "statement", "signature", "workerPublicKey" ] }, { "type": "null" } ], "description": "A signed ownership statement: version 1 proves owner-signed wallet creation; version 2 with basis owner_confirmation proves the owner explicitly confirmed an existing imported account, not attested key generation. Verify the version-specific signed message against your independently pinned worker key and compare the wallet and owner. Null while ownership still needs confirmation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the wallet was created." } }, "required": [ "id", "intentsAccountId", "intentsAccount", "status", "provisionStatus", "ownership", "createdAt" ], "description": "The user's agent wallet: the wallet the agent deposits to, trades from and withdraws from." }, "IntentsAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:[0-9a-f]{64}|0x[0-9a-f]{40})$", "description": "The account 1Click and NEAR Intents know the wallet by: 64 lowercase hex characters for `near`, `0x` and 40 lowercase hex characters for `evm`." }, "kind": { "type": "string", "enum": [ "near", "evm" ], "description": "`near`: the wallet's own implicit NEAR account. `evm`: an Agent API wallet's EVM account, whose key the NEAR Intents Agent API holds for the user." } }, "required": [ "id", "kind" ], "description": "The wallet's NEAR Intents account and its kind: the account its balances are held by, which you need only to read the wallet from 1Click yourself." }, "WalletPortfolioSummary": { "type": "object", "properties": { "availableUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The available wallet balance, identical to `totalUsdCents` outside this summary; null if any held asset is unpriced." }, "inOrdersUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The value of the funds resting in the user's open limit orders, at current prices. Null when an order's report is missing, more than 10 minutes old or unpriced." }, "incomingUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The value of order payouts on their way to the wallet: a filled order's output or a cancelled order's refund, at the amount the order provider reports, before any settlement fee. Zero when nothing is on its way. Once a payout completes, it is part of the available balance instead." }, "totalUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The account's value: available plus in orders plus incoming. Null while any part is unknown; `reasons` says which." }, "pricedSubtotalUsdCents": { "anyOf": [ { "type": "string", "maxLength": 160, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "The sum of priced available-wallet assets only, even when another wallet asset is unpriced. Excludes all order allocations and incoming funds; not a portfolio total. Null if the exact sum exceeds the supported cent-string range." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the available wallet balance was observed." }, "complete": { "type": "boolean", "description": "Whether `totalUsdCents` is known. The total excludes positions held in separate Earn or perps accounts." }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "unpriced_wallet_assets", "order_allocation_unknown", "order_prices_unavailable", "order_settlement_unreconciled", "orders_unavailable", "order_observation_stale", "valuation_out_of_range" ] }, "description": "Why the total is unknown; an empty list means it is known. `order_settlement_unreconciled`: an order's payout failed, or only some of its fills have been paid out, so what is still to come has no amount. `order_allocation_unknown`: an order's amounts aren't reported yet, or a funded order's deposit hasn't been seen yet. `order_observation_stale`: an order holding funds hasn't been read for over 10 minutes." }, "hasAssets": { "description": "True when the wallet holds a positive balance or an order holds or is paying back funds, false only when both are known empty, and null when an order's funds cannot be established. Use false for an empty-state screen; a zero USD value alone does not mean empty.", "type": [ "boolean", "null" ] } }, "required": [ "availableUsdCents", "inOrdersUsdCents", "incomingUsdCents", "totalUsdCents", "pricedSubtotalUsdCents", "asOf", "complete", "reasons", "hasAssets" ], "description": "The account's value: available wallet cash, funds in open orders and order payouts on their way, and their total." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a withdrawal quote 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`. `POST /v1/users/{userId}/wallet/withdrawals/quote` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalQuoteRequestInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/withdrawals/quote' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The quoted terms, the message to sign and the request key. ```json { "description": "The quoted terms, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalQuote" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted - `quote_refused` — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `quote_refused` — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `asset_not_withdrawable` — tokenized stocks cannot be withdrawn; sell them first - `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound - `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_withdrawable` — tokenized stocks cannot be withdrawn; sell them first\n- `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `withdrawal_changed` — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount ```json { "description": "The operation lost to the current state.\n\n- `withdrawal_changed` — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.quoteWithdrawal", "summary": "Get a withdrawal quote", "tags": [ "wallets" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalQuoteRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The quoted terms, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalQuote" } } } }, "400": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `quote_refused` — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_withdrawable` — tokenized stocks cannot be withdrawn; sell them first\n- `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `withdrawal_changed` — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "WithdrawalQuoteRequestInput": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to withdraw from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount to withdraw, in the asset's smallest unit." }, "destination": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the recipient receives: an `id` from List supported assets." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." } }, "required": [ "rail", "network", "assetId", "address" ], "additionalProperties": false, "description": "Where the funds go: the network, the asset received and the recipient's address." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "assetId", "amountRaw", "destination", "maxValueLossBps" ], "additionalProperties": false, "description": "What to withdraw, where it goes, and the most it may lose; the quote fills in the rest." }, "WithdrawalQuote": { "type": "object", "properties": { "terms": { "description": "The exact terms to show the user and send, unchanged, to Withdraw funds: the request plus the minimum the recipient receives and the most the fee can be.", "$ref": "#/components/schemas/WithdrawalTerms" }, "quotedReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the recipient would receive at the current price, in the received asset's smallest unit; they receive at least `terms.minimumReceivedRaw`." }, "quoteExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this price quote runs out. Withdraw funds prices the withdrawal again when it runs, within `terms`." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This withdrawal's id for retries: send it as the `Idempotency-Key` of Withdraw funds, and filter List withdrawals on it after a timeout." }, "authorization": { "description": "The message the user signs to allow exactly these terms. Call Withdraw funds before `authorization.expiresAt`.", "$ref": "#/components/schemas/MessageToSign" } }, "required": [ "terms", "quotedReceivedRaw", "quoteExpiresAt", "requestKey", "authorization" ], "description": "A priced withdrawal, the message the user signs for it, and the key to send it with." }, "WithdrawalTerms": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to withdraw from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount to withdraw, in the asset's smallest unit." }, "destination": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the recipient receives: an `id` from List supported assets." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." } }, "required": [ "rail", "network", "assetId", "address" ], "description": "Where the funds go: the network, the asset received and the recipient's address." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the recipient receives, in the received asset's smallest unit." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The most the withdrawal fee can be, in the received asset's smallest unit. `null` when the provider does not state this fee separately, which does not mean zero; the minimum received and the loss limit still apply." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "assetId", "amountRaw", "destination", "minimumReceivedRaw", "maxFeeRaw", "maxValueLossBps" ], "description": "The exact terms of a withdrawal: what leaves the agent wallet, where it goes, and the limits it must stay within." }, "MessageToSign": { "type": "object", "properties": { "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "message", "controllerId", "expiresAt" ], "description": "A message for the user to sign with their registered wallet or passkey, and the values to send back with the signature." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Withdraw funds 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. `POST /v1/users/{userId}/wallet/withdrawals` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The quote's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same withdrawal back, never a second payout. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/withdrawals' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' \ --header 'Content-Type: application/json' \ --data '{ "terms": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "destination": { "rail": "chain", "network": "eth", "assetId": "asset_2222222222222222222222222222222222222222222222222222222222222222", "address": "0x2222222222222222222222222222222222222222" }, "minimumReceivedRaw": "975000", "maxFeeRaw": null, "maxValueLossBps": 250 }, "authorization": { "controllerId": "ee79012b-d19c-44f8-aef8-828b88142809", "expiresAt": "2026-09-22T18:04:30.000Z", "signature": { "kind": "evm", "signature": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" } } }' ``` ## Responses ### 200 The withdrawal and its current status. Example response ```json { "id": "6e15459a-6fb6-4320-85d8-a320d9e65737", "terms": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "destination": { "rail": "chain", "network": "eth", "assetId": "asset_2222222222222222222222222222222222222222222222222222222222222222", "address": "0x2222222222222222222222222222222222222222" }, "minimumReceivedRaw": "975000", "maxFeeRaw": null, "maxValueLossBps": 250 }, "debit": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000" }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ``` ```json { "description": "The withdrawal and its current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `asset_not_withdrawable` — tokenized stocks cannot be withdrawn; sell them first - `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound - `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_withdrawable` — tokenized stocks cannot be withdrawn; sell them first\n- `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `withdrawal_changed` — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `withdrawal_changed` — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.withdraw", "summary": "Withdraw funds", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The quote's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same withdrawal back, never a second payout. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The withdrawal and its current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_withdrawable` — tokenized stocks cannot be withdrawn; sell them first\n- `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `destination_not_allowed` — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `withdrawal_changed` — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "WithdrawInput": { "type": "object", "properties": { "terms": { "description": "The quote's `terms`, unchanged.", "$ref": "#/components/schemas/WithdrawalTermsInput" }, "authorization": { "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false, "description": "The user's signature of the quote's `authorization.message`, with its `controllerId` and `expiresAt` unchanged. Checked on arrival and never stored." } }, "required": [ "terms", "authorization" ], "additionalProperties": false, "examples": [ { "terms": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "destination": { "rail": "chain", "network": "eth", "assetId": "asset_2222222222222222222222222222222222222222222222222222222222222222", "address": "0x2222222222222222222222222222222222222222" }, "minimumReceivedRaw": "975000", "maxFeeRaw": null, "maxValueLossBps": 250 }, "authorization": { "controllerId": "ee79012b-d19c-44f8-aef8-828b88142809", "expiresAt": "2026-09-22T18:04:30.000Z", "signature": { "kind": "evm", "signature": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" } } } ], "description": "A quoted withdrawal and the user's signature allowing it." }, "WithdrawalTermsInput": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to withdraw from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount to withdraw, in the asset's smallest unit." }, "destination": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the recipient receives: an `id` from List supported assets." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." } }, "required": [ "rail", "network", "assetId", "address" ], "additionalProperties": false, "description": "Where the funds go: the network, the asset received and the recipient's address." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the recipient receives, in the received asset's smallest unit." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The most the withdrawal fee can be, in the received asset's smallest unit. `null` when the provider does not state this fee separately, which does not mean zero; the minimum received and the loss limit still apply." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "assetId", "amountRaw", "destination", "minimumReceivedRaw", "maxFeeRaw", "maxValueLossBps" ], "additionalProperties": false, "description": "The exact terms of a withdrawal: what leaves the agent wallet, where it goes, and the limits it must stay within." }, "Withdrawal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id." }, "terms": { "anyOf": [ { "$ref": "#/components/schemas/WithdrawalTerms" }, { "type": "null" } ], "description": "The signed terms; `null` only for withdrawals made before terms were recorded." }, "debit": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount taken from the agent wallet, in the asset's smallest unit." } }, "required": [ "assetId", "amountRaw" ], "description": "What leaves the agent wallet: the asset and the exact amount." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`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. `completed`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount when the withdrawal started. `quote_rejected`: the price at execution failed its checks or fell outside the signed limits. `quote_expired`: the quote ran out before the provider took the transfer. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the signature no longer covered it when it started, or nothing could sign it then (the automation firing it ran for was not confirmed in time, or the owner's own wallet could not be resolved). `stopped`: an operator paused withdrawals or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign transfers. In every case nothing left the wallet; get a new quote to try again." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the withdrawal was requested." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the withdrawal started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; `null` before then." }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The transfer's id." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based position in the withdrawal plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "amountRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The amount actually received (or refunded), in this asset's smallest unit; `null` until a receipt confirms it." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "The number of decimals of this asset's smallest unit." }, "transferPayout": { "anyOf": [ { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "transactionHashes": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Destination chain transactions, or the funding intent identifiers binding the provider-confirmed ledger payout." }, "quotedFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Withdrawal fee in destination-asset units from the bound signed quote, or null when not disclosed. Actual received amount is recorded separately." } }, "required": [ "rail", "network", "address", "transactionHashes", "quotedFeeRaw" ] }, { "type": "null" } ], "description": "Where the payout landed and its transaction ids; `null` before settlement or for older withdrawals." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this transfer's outcome was observed." } }, "required": [ "id", "index", "state", "assetId", "amountRaw", "decimals", "transferPayout", "refundReason", "observedAt" ] }, "description": "The transfer the withdrawal made and what it received, as evidence." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the debit (`debit.amountRaw`) was worth when the withdrawal ran, at the trusted price Fin checked its plan against. `null` before it has a plan, and when no price was recorded." } }, "required": [ "id", "terms", "debit", "status", "failureReason", "result", "createdAt", "startedAt", "reportedAt", "receipts", "value" ], "examples": [ { "id": "6e15459a-6fb6-4320-85d8-a320d9e65737", "terms": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "destination": { "rail": "chain", "network": "eth", "assetId": "asset_2222222222222222222222222222222222222222222222222222222222222222", "address": "0x2222222222222222222222222222222222222222" }, "minimumReceivedRaw": "975000", "maxFeeRaw": null, "maxValueLossBps": 250 }, "debit": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000" }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ], "description": "A withdrawal from the agent wallet: its terms, its `status`, and the evidence behind it." }, "WithdrawalTerms": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to withdraw from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount to withdraw, in the asset's smallest unit." }, "destination": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the recipient receives: an `id` from List supported assets." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." } }, "required": [ "rail", "network", "assetId", "address" ], "description": "Where the funds go: the network, the asset received and the recipient's address." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the recipient receives, in the received asset's smallest unit." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The most the withdrawal fee can be, in the received asset's smallest unit. `null` when the provider does not state this fee separately, which does not mean zero; the minimum received and the loss limit still apply." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "assetId", "amountRaw", "destination", "minimumReceivedRaw", "maxFeeRaw", "maxValueLossBps" ], "description": "The exact terms of a withdrawal: what leaves the agent wallet, where it goes, and the limits it must stay within." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List withdrawals Lists the user's withdrawals, newest first, with their status. After a timed-out request, find its withdrawal by filtering on `requestKey`. `GET /v1/users/{userId}/wallet/withdrawals` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "requestKey", "required": false, "description": "Only the withdrawal sent with this `Idempotency-Key`: how to find it after a request timed out." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/withdrawals' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of withdrawals. ```json { "description": "A page of withdrawals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Withdrawal" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.listWithdrawals", "summary": "List withdrawals", "tags": [ "wallets" ], "description": "Lists the user's withdrawals, newest first, with their status. After a timed-out request, find its withdrawal by filtering on `requestKey`.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "requestKey", "required": false, "description": "Only the withdrawal sent with this `Idempotency-Key`: how to find it after a request timed out." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of withdrawals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Withdrawal" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Withdrawal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id." }, "terms": { "anyOf": [ { "$ref": "#/components/schemas/WithdrawalTerms" }, { "type": "null" } ], "description": "The signed terms; `null` only for withdrawals made before terms were recorded." }, "debit": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount taken from the agent wallet, in the asset's smallest unit." } }, "required": [ "assetId", "amountRaw" ], "description": "What leaves the agent wallet: the asset and the exact amount." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`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. `completed`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount when the withdrawal started. `quote_rejected`: the price at execution failed its checks or fell outside the signed limits. `quote_expired`: the quote ran out before the provider took the transfer. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the signature no longer covered it when it started, or nothing could sign it then (the automation firing it ran for was not confirmed in time, or the owner's own wallet could not be resolved). `stopped`: an operator paused withdrawals or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign transfers. In every case nothing left the wallet; get a new quote to try again." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the withdrawal was requested." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the withdrawal started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; `null` before then." }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The transfer's id." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based position in the withdrawal plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "amountRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The amount actually received (or refunded), in this asset's smallest unit; `null` until a receipt confirms it." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "The number of decimals of this asset's smallest unit." }, "transferPayout": { "anyOf": [ { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "transactionHashes": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Destination chain transactions, or the funding intent identifiers binding the provider-confirmed ledger payout." }, "quotedFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Withdrawal fee in destination-asset units from the bound signed quote, or null when not disclosed. Actual received amount is recorded separately." } }, "required": [ "rail", "network", "address", "transactionHashes", "quotedFeeRaw" ] }, { "type": "null" } ], "description": "Where the payout landed and its transaction ids; `null` before settlement or for older withdrawals." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this transfer's outcome was observed." } }, "required": [ "id", "index", "state", "assetId", "amountRaw", "decimals", "transferPayout", "refundReason", "observedAt" ] }, "description": "The transfer the withdrawal made and what it received, as evidence." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the debit (`debit.amountRaw`) was worth when the withdrawal ran, at the trusted price Fin checked its plan against. `null` before it has a plan, and when no price was recorded." } }, "required": [ "id", "terms", "debit", "status", "failureReason", "result", "createdAt", "startedAt", "reportedAt", "receipts", "value" ], "examples": [ { "id": "6e15459a-6fb6-4320-85d8-a320d9e65737", "terms": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "destination": { "rail": "chain", "network": "eth", "assetId": "asset_2222222222222222222222222222222222222222222222222222222222222222", "address": "0x2222222222222222222222222222222222222222" }, "minimumReceivedRaw": "975000", "maxFeeRaw": null, "maxValueLossBps": 250 }, "debit": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000" }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ], "description": "A withdrawal from the agent wallet: its terms, its `status`, and the evidence behind it." }, "WithdrawalTerms": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to withdraw from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount to withdraw, in the asset's smallest unit." }, "destination": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the recipient receives: an `id` from List supported assets." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." } }, "required": [ "rail", "network", "assetId", "address" ], "description": "Where the funds go: the network, the asset received and the recipient's address." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the recipient receives, in the received asset's smallest unit." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The most the withdrawal fee can be, in the received asset's smallest unit. `null` when the provider does not state this fee separately, which does not mean zero; the minimum received and the loss limit still apply." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "assetId", "amountRaw", "destination", "minimumReceivedRaw", "maxFeeRaw", "maxValueLossBps" ], "description": "The exact terms of a withdrawal: what leaves the agent wallet, where it goes, and the limits it must stay within." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a withdrawal 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. `GET /v1/users/{userId}/wallet/withdrawals/{withdrawalId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "withdrawalId", "required": true, "description": "The withdrawal's id, as Withdraw funds returned it." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/withdrawals/YOUR_WITHDRAWAL_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The withdrawal and its status. Example response ```json { "id": "6e15459a-6fb6-4320-85d8-a320d9e65737", "terms": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "destination": { "rail": "chain", "network": "eth", "assetId": "asset_2222222222222222222222222222222222222222222222222222222222222222", "address": "0x2222222222222222222222222222222222222222" }, "minimumReceivedRaw": "975000", "maxFeeRaw": null, "maxValueLossBps": 250 }, "debit": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000" }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ``` ```json { "description": "The withdrawal and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getWithdrawal", "summary": "Get a withdrawal", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "withdrawalId", "required": true, "description": "The withdrawal's id, as Withdraw funds returned it." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The withdrawal and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Withdrawal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id." }, "terms": { "anyOf": [ { "$ref": "#/components/schemas/WithdrawalTerms" }, { "type": "null" } ], "description": "The signed terms; `null` only for withdrawals made before terms were recorded." }, "debit": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount taken from the agent wallet, in the asset's smallest unit." } }, "required": [ "assetId", "amountRaw" ], "description": "What leaves the agent wallet: the asset and the exact amount." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`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. `completed`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount when the withdrawal started. `quote_rejected`: the price at execution failed its checks or fell outside the signed limits. `quote_expired`: the quote ran out before the provider took the transfer. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the signature no longer covered it when it started, or nothing could sign it then (the automation firing it ran for was not confirmed in time, or the owner's own wallet could not be resolved). `stopped`: an operator paused withdrawals or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign transfers. In every case nothing left the wallet; get a new quote to try again." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the withdrawal was requested." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the withdrawal started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; `null` before then." }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The transfer's id." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based position in the withdrawal plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "amountRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The amount actually received (or refunded), in this asset's smallest unit; `null` until a receipt confirms it." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "The number of decimals of this asset's smallest unit." }, "transferPayout": { "anyOf": [ { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "transactionHashes": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Destination chain transactions, or the funding intent identifiers binding the provider-confirmed ledger payout." }, "quotedFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Withdrawal fee in destination-asset units from the bound signed quote, or null when not disclosed. Actual received amount is recorded separately." } }, "required": [ "rail", "network", "address", "transactionHashes", "quotedFeeRaw" ] }, { "type": "null" } ], "description": "Where the payout landed and its transaction ids; `null` before settlement or for older withdrawals." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this transfer's outcome was observed." } }, "required": [ "id", "index", "state", "assetId", "amountRaw", "decimals", "transferPayout", "refundReason", "observedAt" ] }, "description": "The transfer the withdrawal made and what it received, as evidence." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the debit (`debit.amountRaw`) was worth when the withdrawal ran, at the trusted price Fin checked its plan against. `null` before it has a plan, and when no price was recorded." } }, "required": [ "id", "terms", "debit", "status", "failureReason", "result", "createdAt", "startedAt", "reportedAt", "receipts", "value" ], "examples": [ { "id": "6e15459a-6fb6-4320-85d8-a320d9e65737", "terms": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "destination": { "rail": "chain", "network": "eth", "assetId": "asset_2222222222222222222222222222222222222222222222222222222222222222", "address": "0x2222222222222222222222222222222222222222" }, "minimumReceivedRaw": "975000", "maxFeeRaw": null, "maxValueLossBps": 250 }, "debit": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000" }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ], "description": "A withdrawal from the agent wallet: its terms, its `status`, and the evidence behind it." }, "WithdrawalTerms": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to withdraw from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount to withdraw, in the asset's smallest unit." }, "destination": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the recipient receives: an `id` from List supported assets." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." } }, "required": [ "rail", "network", "assetId", "address" ], "description": "Where the funds go: the network, the asset received and the recipient's address." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the recipient receives, in the received asset's smallest unit." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The most the withdrawal fee can be, in the received asset's smallest unit. `null` when the provider does not state this fee separately, which does not mean zero; the minimum received and the loss limit still apply." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "assetId", "amountRaw", "destination", "minimumReceivedRaw", "maxFeeRaw", "maxValueLossBps" ], "description": "The exact terms of a withdrawal: what leaves the agent wallet, where it goes, and the limits it must stay within." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List supported assets 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 /v1/users/{userId}/wallet/supported-assets` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/supported-assets' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The supported assets and networks. ```json { "description": "The supported assets and networks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportedAssets" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.supportedAssets", "summary": "List supported assets", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The supported assets and networks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportedAssets" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "SupportedAssets": { "type": "object", "properties": { "networks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "depositWindowSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Time allowed to initiate and confirm a deposit; actual instructions contain exact deadlines." }, "addressRouting": { "type": "string", "const": "encoded_address", "description": "Recipient and refund routing must be encoded in the network address. Standalone recipient/refund memos are not accepted by this provider." } }, "required": [ "id", "rail", "depositWindowSeconds", "addressRouting" ] }, "description": "The networks funds can arrive from and leave to: blockchains, plus the NEAR Intents and confidential NEAR Intents ledgers." }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ] }, "description": "The assets that can be deposited and withdrawn, with the `id` to use in deposit and withdrawal requests." } }, "required": [ "networks", "assets" ], "description": "The assets and networks the agent wallet can deposit and withdraw." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a deposit quote 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. `POST /v1/users/{userId}/wallet/deposits/quote` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositQuoteRequestInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/deposits/quote' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 What the deposit would credit now, and the least it will. ```json { "description": "What the deposit would credit now, and the least it will.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositQuote" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.quoteDeposit", "summary": "Get a deposit quote", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositQuoteRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "What the deposit would credit now, and the least it will.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositQuote" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "DepositQuoteRequestInput": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to deposit: an `id` from List supported assets." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount the user would send, in the asset's smallest unit." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "rail", "network", "assetId", "amountRaw", "maxValueLossBps" ], "additionalProperties": false, "description": "The deposit to price: what the user would send, from which network, how much, and the most it may lose." }, "DepositQuote": { "type": "object", "properties": { "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the agent wallet would be credited now for `amountRaw`, in the asset's smallest unit: 1Click's own figure at the current price." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet is credited within `maxValueLossBps`: the amount less the loss limit, rounded up. Send it as `terms.minimumCreditRaw` to Create a deposit, which holds the deposit to it." }, "quotedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When 1Click priced it. A preview binds nothing: Create a deposit prices the deposit again when it issues the address, so quote again if the user lingers." } }, "required": [ "expectedCreditRaw", "minimumCreditRaw", "quotedAt" ], "description": "What a deposit of an exact amount would credit the agent wallet now, and the least it will." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Create a deposit 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. `POST /v1/users/{userId}/wallet/deposits` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepositInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/deposits' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The deposit and where to send the funds. ```json { "description": "The deposit and where to send the funds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` the deposit was created with; filter List deposits on it." }, "terms": { "$ref": "#/components/schemas/DepositTerms" }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `failed` means no address was issued. `expired` means the deadline passed with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified native blockchain.", "enum": [ "chain" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet broadcasts a native-chain transfer using these instructions.", "enum": [ "chain_transfer" ] } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind" ] }, { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified public or confidential Intents ledger.", "enum": [ "intents" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet signs and submits a transfer intent on the specified ledger.", "enum": [ "intents_transfer" ] }, "protocol": { "type": "object", "properties": { "verifier": { "type": "string", "enum": [ "intents.near", "intents.far" ], "description": "Ledger verifier for the external wallet's signed transfer intent." }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ledger protocol asset identifier, exposed only for explicit advanced Intents funding." }, "depositAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Quote deposit account, used by the external wallet to generate the exact signed transfer intent; identical to the instruction address." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact signed transfer amount." } }, "required": [ "verifier", "assetId", "depositAddress", "amountRaw" ], "description": "The external wallet constructs and signs a transfer intent with its own authority. Fin does not sign for or hold credentials to that source wallet." } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind", "protocol" ] } ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When trusted provider evidence was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Provider-established terminal financial outcome." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Observed source amount." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Actual wallet credit; zero on full refund." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Amount refunded to the approved source destination." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed source transactions or ledger intent identifiers bound to the instruction." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed refund transactions or ledger intent identifiers." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What was credited or refunded; `null` until that is observed." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit last changed." } }, "required": [ "id", "requestKey", "terms", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `deposit_limit_exceeded` — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `deposit_limit_exceeded` — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.createDeposit", "summary": "Create a deposit", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepositInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The deposit and where to send the funds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` the deposit was created with; filter List deposits on it." }, "terms": { "$ref": "#/components/schemas/DepositTerms" }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `failed` means no address was issued. `expired` means the deadline passed with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified native blockchain.", "enum": [ "chain" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet broadcasts a native-chain transfer using these instructions.", "enum": [ "chain_transfer" ] } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind" ] }, { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified public or confidential Intents ledger.", "enum": [ "intents" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet signs and submits a transfer intent on the specified ledger.", "enum": [ "intents_transfer" ] }, "protocol": { "type": "object", "properties": { "verifier": { "type": "string", "enum": [ "intents.near", "intents.far" ], "description": "Ledger verifier for the external wallet's signed transfer intent." }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ledger protocol asset identifier, exposed only for explicit advanced Intents funding." }, "depositAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Quote deposit account, used by the external wallet to generate the exact signed transfer intent; identical to the instruction address." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact signed transfer amount." } }, "required": [ "verifier", "assetId", "depositAddress", "amountRaw" ], "description": "The external wallet constructs and signs a transfer intent with its own authority. Fin does not sign for or hold credentials to that source wallet." } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind", "protocol" ] } ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When trusted provider evidence was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Provider-established terminal financial outcome." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Observed source amount." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Actual wallet credit; zero on full refund." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Amount refunded to the approved source destination." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed source transactions or ledger intent identifiers bound to the instruction." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed refund transactions or ledger intent identifiers." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What was credited or refunded; `null` until that is observed." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit last changed." } }, "required": [ "id", "requestKey", "terms", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `deposit_limit_exceeded` — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "CreateDepositInput": { "type": "object", "properties": { "terms": { "description": "What the user sends, the least the wallet must be credited, and where a refund goes.", "$ref": "#/components/schemas/DepositTermsInput" } }, "required": [ "terms" ], "additionalProperties": false, "description": "The terms of a deposit into the agent wallet." }, "DepositTermsInput": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to deposit: an `id` from List supported assets." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount the user sends, in the asset's smallest unit." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Where the funds go back to if the deposit cannot be credited: an address the user controls on the network they send from." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet must be credited, in the same asset's smallest unit." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "rail", "network", "assetId", "amountRaw", "refundAddress", "minimumCreditRaw", "maxValueLossBps" ], "additionalProperties": false, "description": "The exact terms of a deposit: what the user sends, from which network, and the limits the credit must stay within." }, "DepositTerms": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to deposit: an `id` from List supported assets." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount the user sends, in the asset's smallest unit." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Where the funds go back to if the deposit cannot be credited: an address the user controls on the network they send from." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet must be credited, in the same asset's smallest unit." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "rail", "network", "assetId", "amountRaw", "refundAddress", "minimumCreditRaw", "maxValueLossBps" ], "description": "The exact terms of a deposit: what the user sends, from which network, and the limits the credit must stay within." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List deposits 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 /v1/users/{userId}/wallet/deposits` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "requestKey", "required": false, "description": "Only the deposit created with this `Idempotency-Key`: how to find it after a request timed out." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/deposits' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of deposits. ```json { "description": "A page of deposits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` the deposit was created with; filter List deposits on it." }, "terms": { "$ref": "#/components/schemas/DepositTerms" }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `failed` means no address was issued. `expired` means the deadline passed with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified native blockchain.", "enum": [ "chain" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet broadcasts a native-chain transfer using these instructions.", "enum": [ "chain_transfer" ] } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind" ] }, { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified public or confidential Intents ledger.", "enum": [ "intents" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet signs and submits a transfer intent on the specified ledger.", "enum": [ "intents_transfer" ] }, "protocol": { "type": "object", "properties": { "verifier": { "type": "string", "enum": [ "intents.near", "intents.far" ], "description": "Ledger verifier for the external wallet's signed transfer intent." }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ledger protocol asset identifier, exposed only for explicit advanced Intents funding." }, "depositAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Quote deposit account, used by the external wallet to generate the exact signed transfer intent; identical to the instruction address." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact signed transfer amount." } }, "required": [ "verifier", "assetId", "depositAddress", "amountRaw" ], "description": "The external wallet constructs and signs a transfer intent with its own authority. Fin does not sign for or hold credentials to that source wallet." } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind", "protocol" ] } ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When trusted provider evidence was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Provider-established terminal financial outcome." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Observed source amount." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Actual wallet credit; zero on full refund." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Amount refunded to the approved source destination." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed source transactions or ledger intent identifiers bound to the instruction." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed refund transactions or ledger intent identifiers." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What was credited or refunded; `null` until that is observed." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit last changed." } }, "required": [ "id", "requestKey", "terms", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ] }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.listDeposits", "summary": "List deposits", "tags": [ "wallets" ], "description": "Lists the user's deposits, newest first. After a timed-out request, find its deposit by filtering on `requestKey` (the `Idempotency-Key` you sent).", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "requestKey", "required": false, "description": "Only the deposit created with this `Idempotency-Key`: how to find it after a request timed out." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of deposits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` the deposit was created with; filter List deposits on it." }, "terms": { "$ref": "#/components/schemas/DepositTerms" }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `failed` means no address was issued. `expired` means the deadline passed with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified native blockchain.", "enum": [ "chain" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet broadcasts a native-chain transfer using these instructions.", "enum": [ "chain_transfer" ] } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind" ] }, { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified public or confidential Intents ledger.", "enum": [ "intents" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet signs and submits a transfer intent on the specified ledger.", "enum": [ "intents_transfer" ] }, "protocol": { "type": "object", "properties": { "verifier": { "type": "string", "enum": [ "intents.near", "intents.far" ], "description": "Ledger verifier for the external wallet's signed transfer intent." }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ledger protocol asset identifier, exposed only for explicit advanced Intents funding." }, "depositAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Quote deposit account, used by the external wallet to generate the exact signed transfer intent; identical to the instruction address." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact signed transfer amount." } }, "required": [ "verifier", "assetId", "depositAddress", "amountRaw" ], "description": "The external wallet constructs and signs a transfer intent with its own authority. Fin does not sign for or hold credentials to that source wallet." } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind", "protocol" ] } ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When trusted provider evidence was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Provider-established terminal financial outcome." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Observed source amount." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Actual wallet credit; zero on full refund." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Amount refunded to the approved source destination." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed source transactions or ledger intent identifiers bound to the instruction." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed refund transactions or ledger intent identifiers." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What was credited or refunded; `null` until that is observed." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit last changed." } }, "required": [ "id", "requestKey", "terms", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ] }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "DepositTerms": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to deposit: an `id` from List supported assets." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount the user sends, in the asset's smallest unit." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Where the funds go back to if the deposit cannot be credited: an address the user controls on the network they send from." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet must be credited, in the same asset's smallest unit." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "rail", "network", "assetId", "amountRaw", "refundAddress", "minimumCreditRaw", "maxValueLossBps" ], "description": "The exact terms of a deposit: what the user sends, from which network, and the limits the credit must stay within." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a deposit Returns a deposit and its status: waiting for funds, credited or refunded. Each read checks the provider for news. `GET /v1/users/{userId}/wallet/deposits/{depositId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "depositId", "required": true, "description": "The deposit's id, as Create a deposit returned it." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/deposits/YOUR_DEPOSIT_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The deposit and its status. ```json { "description": "The deposit and its status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` the deposit was created with; filter List deposits on it." }, "terms": { "$ref": "#/components/schemas/DepositTerms" }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `failed` means no address was issued. `expired` means the deadline passed with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified native blockchain.", "enum": [ "chain" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet broadcasts a native-chain transfer using these instructions.", "enum": [ "chain_transfer" ] } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind" ] }, { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified public or confidential Intents ledger.", "enum": [ "intents" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet signs and submits a transfer intent on the specified ledger.", "enum": [ "intents_transfer" ] }, "protocol": { "type": "object", "properties": { "verifier": { "type": "string", "enum": [ "intents.near", "intents.far" ], "description": "Ledger verifier for the external wallet's signed transfer intent." }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ledger protocol asset identifier, exposed only for explicit advanced Intents funding." }, "depositAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Quote deposit account, used by the external wallet to generate the exact signed transfer intent; identical to the instruction address." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact signed transfer amount." } }, "required": [ "verifier", "assetId", "depositAddress", "amountRaw" ], "description": "The external wallet constructs and signs a transfer intent with its own authority. Fin does not sign for or hold credentials to that source wallet." } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind", "protocol" ] } ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When trusted provider evidence was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Provider-established terminal financial outcome." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Observed source amount." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Actual wallet credit; zero on full refund." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Amount refunded to the approved source destination." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed source transactions or ledger intent identifiers bound to the instruction." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed refund transactions or ledger intent identifiers." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What was credited or refunded; `null` until that is observed." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit last changed." } }, "required": [ "id", "requestKey", "terms", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getDeposit", "summary": "Get a deposit", "tags": [ "wallets" ], "description": "Returns a deposit and its status: waiting for funds, credited or refunded. Each read checks the provider for news.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "depositId", "required": true, "description": "The deposit's id, as Create a deposit returned it." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The deposit and its status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` the deposit was created with; filter List deposits on it." }, "terms": { "$ref": "#/components/schemas/DepositTerms" }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `failed` means no address was issued. `expired` means the deadline passed with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified native blockchain.", "enum": [ "chain" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet broadcasts a native-chain transfer using these instructions.", "enum": [ "chain_transfer" ] } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind" ] }, { "type": "object", "properties": { "rail": { "type": "string", "description": "Payment originates on the specified public or confidential Intents ledger.", "enum": [ "intents" ] }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "description": "Bound to one funding request; never reuse for a later transfer.", "enum": [ false ] }, "kind": { "type": "string", "description": "The external wallet signs and submits a transfer intent on the specified ledger.", "enum": [ "intents_transfer" ] }, "protocol": { "type": "object", "properties": { "verifier": { "type": "string", "enum": [ "intents.near", "intents.far" ], "description": "Ledger verifier for the external wallet's signed transfer intent." }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ledger protocol asset identifier, exposed only for explicit advanced Intents funding." }, "depositAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Quote deposit account, used by the external wallet to generate the exact signed transfer intent; identical to the instruction address." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact signed transfer amount." } }, "required": [ "verifier", "assetId", "depositAddress", "amountRaw" ], "description": "The external wallet constructs and signs a transfer intent with its own authority. Fin does not sign for or hold credentials to that source wallet." } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind", "protocol" ] } ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When trusted provider evidence was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Provider-established terminal financial outcome." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Observed source amount." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Actual wallet credit; zero on full refund." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Amount refunded to the approved source destination." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed source transactions or ledger intent identifiers bound to the instruction." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed refund transactions or ledger intent identifiers." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What was credited or refunded; `null` until that is observed." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit last changed." } }, "required": [ "id", "requestKey", "terms", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "DepositTerms": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to deposit: an `id` from List supported assets." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount the user sends, in the asset's smallest unit." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Where the funds go back to if the deposit cannot be credited: an address the user controls on the network they send from." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet must be credited, in the same asset's smallest unit." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "rail", "network", "assetId", "amountRaw", "refundAddress", "minimumCreditRaw", "maxValueLossBps" ], "description": "The exact terms of a deposit: what the user sends, from which network, and the limits the credit must stay within." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Create a deposit address 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. `POST /v1/users/{userId}/wallet/deposit-addresses` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepositAddressInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/deposit-addresses' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The deposit address and what to send to it. ```json { "description": "The deposit address and what to send to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddress" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted - `quote_refused` — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `quote_refused` — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `deposit_limit_exceeded` — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `deposit_limit_exceeded` — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.createDepositAddress", "summary": "Create a deposit address", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepositAddressInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The deposit address and what to send to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddress" } } } }, "400": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `quote_refused` — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `deposit_limit_exceeded` — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "CreateDepositAddressInput": { "type": "object", "properties": { "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The network the user sends on: a blockchain network from List supported assets, never an Intents ledger." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the user sends: an `id` from List supported assets, listed on that network." } }, "required": [ "network", "assetId" ], "additionalProperties": false, "description": "The asset and network of a deposit whose amount is not known yet." }, "DepositAddress": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` it was created with." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The network the user sends on." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the user sends: an `id` from List supported assets." }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "incomplete", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `incomplete` means less than `minimumDepositRaw` arrived: it is refunded to the agent wallet, so tell the user not to top it up. `failed` means no address was issued. `expired` means the address stopped taking deposits with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "The asset to send, on its network, and the precision its amounts are in." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "The one-time address to send to. It takes one transfer: never save or reuse it." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "minimumDepositRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least one transfer must carry to be credited, in the asset's smallest unit. Less is refunded to the agent wallet." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Send by this time; a transfer sent later may be refunded instead of credited." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the address stops taking deposits. A transfer that arrives later is still watched, and refunded to the agent wallet." }, "creditEstimateSeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 86400 }, { "type": "null" } ], "description": "About how long the credit takes once the network has confirmed the transfer, in seconds; null when no estimate was given." } }, "required": [ "asset", "address", "memo", "minimumDepositRaw", "sendBefore", "expiresAt", "creditEstimateSeconds" ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the outcome was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Whether the transfer was credited or refunded." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What arrived at the address." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the agent wallet was credited; zero when all of it was refunded." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What went back to the agent wallet uncredited, such as a transfer below the minimum." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The transfers that paid the address, on the network they were sent on." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The refund's ledger identifiers, when they were reported." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What arrived, what was credited and what was refunded; `null` until then." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit address was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed." } }, "required": [ "id", "requestKey", "network", "assetId", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ], "description": "A one-time address that takes one transfer of any amount into the agent wallet, and how that transfer is going." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a deposit address 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. `GET /v1/users/{userId}/wallet/deposit-addresses/{depositAddressId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "depositAddressId", "required": true, "description": "The deposit address's id, as Create a deposit address returned it." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/deposit-addresses/YOUR_DEPOSIT_ADDRESS_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The deposit address and its status. ```json { "description": "The deposit address and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddress" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getDepositAddress", "summary": "Get a deposit address", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "depositAddressId", "required": true, "description": "The deposit address's id, as Create a deposit address returned it." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The deposit address and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddress" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "DepositAddress": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` it was created with." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The network the user sends on." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the user sends: an `id` from List supported assets." }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "incomplete", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `incomplete` means less than `minimumDepositRaw` arrived: it is refunded to the agent wallet, so tell the user not to top it up. `failed` means no address was issued. `expired` means the address stopped taking deposits with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "The asset to send, on its network, and the precision its amounts are in." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "The one-time address to send to. It takes one transfer: never save or reuse it." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "minimumDepositRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least one transfer must carry to be credited, in the asset's smallest unit. Less is refunded to the agent wallet." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Send by this time; a transfer sent later may be refunded instead of credited." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the address stops taking deposits. A transfer that arrives later is still watched, and refunded to the agent wallet." }, "creditEstimateSeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 86400 }, { "type": "null" } ], "description": "About how long the credit takes once the network has confirmed the transfer, in seconds; null when no estimate was given." } }, "required": [ "asset", "address", "memo", "minimumDepositRaw", "sendBefore", "expiresAt", "creditEstimateSeconds" ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the outcome was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Whether the transfer was credited or refunded." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What arrived at the address." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the agent wallet was credited; zero when all of it was refunded." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What went back to the agent wallet uncredited, such as a transfer below the minimum." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The transfers that paid the address, on the network they were sent on." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The refund's ledger identifiers, when they were reported." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What arrived, what was credited and what was refunded; `null` until then." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit address was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed." } }, "required": [ "id", "requestKey", "network", "assetId", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ], "description": "A one-time address that takes one transfer of any amount into the agent wallet, and how that transfer is going." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Report a deposit transaction 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. `POST /v1/users/{userId}/wallet/deposit-addresses/{depositAddressId}/transactions` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "depositAddressId", "required": true, "description": "The deposit address's id, as Create a deposit address returned it." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDepositTransactionInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/deposit-addresses/YOUR_DEPOSIT_ADDRESS_ID/transactions' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The deposit address and its status. ```json { "description": "The deposit address and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddress" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.reportDepositTransaction", "summary": "Report a deposit transaction", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDepositTransactionInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "depositAddressId", "required": true, "description": "The deposit address's id, as Create a deposit address returned it." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The deposit address and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddress" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "ReportDepositTransactionInput": { "type": "object", "properties": { "transactionHash": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "The hash of the transfer the user sent to the address, as their wallet or exchange shows it." } }, "required": [ "transactionHash" ], "additionalProperties": false, "description": "The transfer that paid a deposit address." }, "DepositAddress": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` it was created with." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The network the user sends on." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the user sends: an `id` from List supported assets." }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "incomplete", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `incomplete` means less than `minimumDepositRaw` arrived: it is refunded to the agent wallet, so tell the user not to top it up. `failed` means no address was issued. `expired` means the address stopped taking deposits with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "The asset to send, on its network, and the precision its amounts are in." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "The one-time address to send to. It takes one transfer: never save or reuse it." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "minimumDepositRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least one transfer must carry to be credited, in the asset's smallest unit. Less is refunded to the agent wallet." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Send by this time; a transfer sent later may be refunded instead of credited." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the address stops taking deposits. A transfer that arrives later is still watched, and refunded to the agent wallet." }, "creditEstimateSeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 86400 }, { "type": "null" } ], "description": "About how long the credit takes once the network has confirmed the transfer, in seconds; null when no estimate was given." } }, "required": [ "asset", "address", "memo", "minimumDepositRaw", "sendBefore", "expiresAt", "creditEstimateSeconds" ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the outcome was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Whether the transfer was credited or refunded." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What arrived at the address." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the agent wallet was credited; zero when all of it was refunded." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What went back to the agent wallet uncredited, such as a transfer below the minimum." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The transfers that paid the address, on the network they were sent on." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The refund's ledger identifiers, when they were reported." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What arrived, what was credited and what was refunded; `null` until then." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit address was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed." } }, "required": [ "id", "requestKey", "network", "assetId", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ], "description": "A one-time address that takes one transfer of any amount into the agent wallet, and how that transfer is going." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List earn vaults 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 /v1/users/{userId}/wallet/earn-vaults` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/earn-vaults' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The curated vaults, the rate each provider states now and the user's position in each. ```json { "description": "The curated vaults, the rate each provider states now and the user's position in each.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1, "description": "The vault share token's exact 1Click asset id, as the vault table names it." }, "symbol": { "type": "string", "minLength": 1, "description": "The share token's symbol, e.g. `gtUSDCp`." }, "name": { "type": "string", "minLength": 1, "description": "The vault's name, e.g. `Gauntlet USDC`." }, "provider": { "type": "string", "minLength": 1, "description": "Who manages the vault's strategy." }, "rate": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(?:\\.\\d{1,18})?$", "description": "The yearly rate in percent, as the provider states it: `5.4017` is 5.4017%." }, "type": { "type": "string", "enum": [ "APY", "APR" ], "description": "`APY` compounds within the year; `APR` does not. The provider says which." }, "source": { "type": "string", "enum": [ "yield_xyz", "taler" ], "description": "Who states the rate: Yield.xyz, or Taler's own vault API." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin read the rate from that source." } }, "required": [ "percent", "type", "source", "observedAt" ] }, { "type": "null" } ], "description": "The provider's current rate, or null when it could not be read now; never a guess." }, "tvlUsd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(?:\\.\\d{1,18})?$" }, { "type": "null" } ], "description": "The vault's total value locked in US dollars, as its provider states it." }, "payment": { "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1, "description": "Its exact 1Click asset id." }, "symbol": { "type": "string", "minLength": 1, "description": "Its symbol, e.g. `USDC`." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many decimals its raw amounts carry." } }, "required": [ "assetId", "symbol", "decimals" ], "description": "The asset a deposit into the vault pays with and a withdrawal returns." }, "position": { "anyOf": [ { "type": "object", "properties": { "sharesRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The shares the agent holds now, in the share token's smallest unit, those set aside for a resting order included." }, "firstDepositAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the share balance last rose from zero: when this position began." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What buying the shares paid, fees included, in the payment asset's smallest unit." }, "withdrawnRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What selling shares returned, in the payment asset's smallest unit." }, "costBasisStatus": { "type": "string", "enum": [ "complete", "partial" ], "description": "`complete` when trades in the payment asset explain every share held; `partial` when shares also moved another way (transferred in or out, or traded for another asset), so the two amounts do not tell what the shares cost and no earned figure can be worked out from them." } }, "required": [ "sharesRaw", "firstDepositAt", "depositedRaw", "withdrawnRaw", "costBasisStatus" ] }, { "type": "null" } ], "description": "The user's own position in the vault; null when the agent's records show no shares of it." } }, "required": [ "assetId", "symbol", "name", "provider", "rate", "tvlUsd", "payment", "position" ] }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.listEarnVaults", "summary": "List earn vaults", "tags": [ "wallets" ], "description": "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`.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The curated vaults, the rate each provider states now and the user's position in each.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1, "description": "The vault share token's exact 1Click asset id, as the vault table names it." }, "symbol": { "type": "string", "minLength": 1, "description": "The share token's symbol, e.g. `gtUSDCp`." }, "name": { "type": "string", "minLength": 1, "description": "The vault's name, e.g. `Gauntlet USDC`." }, "provider": { "type": "string", "minLength": 1, "description": "Who manages the vault's strategy." }, "rate": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(?:\\.\\d{1,18})?$", "description": "The yearly rate in percent, as the provider states it: `5.4017` is 5.4017%." }, "type": { "type": "string", "enum": [ "APY", "APR" ], "description": "`APY` compounds within the year; `APR` does not. The provider says which." }, "source": { "type": "string", "enum": [ "yield_xyz", "taler" ], "description": "Who states the rate: Yield.xyz, or Taler's own vault API." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin read the rate from that source." } }, "required": [ "percent", "type", "source", "observedAt" ] }, { "type": "null" } ], "description": "The provider's current rate, or null when it could not be read now; never a guess." }, "tvlUsd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,17})(?:\\.\\d{1,18})?$" }, { "type": "null" } ], "description": "The vault's total value locked in US dollars, as its provider states it." }, "payment": { "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1, "description": "Its exact 1Click asset id." }, "symbol": { "type": "string", "minLength": 1, "description": "Its symbol, e.g. `USDC`." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many decimals its raw amounts carry." } }, "required": [ "assetId", "symbol", "decimals" ], "description": "The asset a deposit into the vault pays with and a withdrawal returns." }, "position": { "anyOf": [ { "type": "object", "properties": { "sharesRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The shares the agent holds now, in the share token's smallest unit, those set aside for a resting order included." }, "firstDepositAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the share balance last rose from zero: when this position began." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What buying the shares paid, fees included, in the payment asset's smallest unit." }, "withdrawnRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What selling shares returned, in the payment asset's smallest unit." }, "costBasisStatus": { "type": "string", "enum": [ "complete", "partial" ], "description": "`complete` when trades in the payment asset explain every share held; `partial` when shares also moved another way (transferred in or out, or traded for another asset), so the two amounts do not tell what the shares cost and no earned figure can be worked out from them." } }, "required": [ "sharesRaw", "firstDepositAt", "depositedRaw", "withdrawnRaw", "costBasisStatus" ] }, { "type": "null" } ], "description": "The user's own position in the vault; null when the agent's records show no shares of it." } }, "required": [ "assetId", "symbol", "name", "provider", "rate", "tvlUsd", "payment", "position" ] }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a swap quote 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`. `POST /v1/users/{userId}/wallet/swaps/quote` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapQuoteRequestInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/swaps/quote' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The quoted terms, the message to sign and the request key. ```json { "description": "The quoted terms, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapQuote" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted - `quote_refused` — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `quote_refused` — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `asset_not_swappable` — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off - `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_swappable` — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `swap_changed` — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote ```json { "description": "The operation lost to the current state.\n\n- `swap_changed` — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.quoteSwap", "summary": "Get a swap quote", "tags": [ "wallets" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapQuoteRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The quoted terms, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapQuote" } } } }, "400": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted\n- `quote_refused` — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_swappable` — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `swap_changed` — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "SwapQuoteRequestInput": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. It stays in the agent wallet." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the swap may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." }, "context": { "type": "object", "properties": { "country": { "description": "The country the user is making this request from, as an uppercase ISO 3166-1 alpha-2 code such as `GB`, resolved by your server from the request (your edge's IP geolocation), never taken from the browser. A tokenized stock is traded only when this reports a country where it is available.", "type": "string", "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false, "description": "What your app knows about the user as they make this request. It applies to this request only, so send it with every request that may trade a tokenized stock." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "maxValueLossBps" ], "additionalProperties": false, "description": "What to sell, how much, what to buy, and the most the swap may lose; the quote fills in the rest. A swap of a tokenized stock also needs `context.country`." }, "SwapQuote": { "type": "object", "properties": { "terms": { "description": "The exact terms to show the user and send, unchanged, to Swap tokens: the request plus the least the agent wallet receives.", "$ref": "#/components/schemas/SwapTerms" }, "quotedReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the swap would receive at the current price, in the bought asset's smallest unit; it receives at least `terms.minimumReceivedRaw`." }, "quoteExpiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this price quote runs out. Swap tokens prices the swap again when it runs, within `terms`." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This swap's id for retries: send it as the `Idempotency-Key` of Swap tokens, and filter List swaps on it after a timeout." }, "authorization": { "description": "The message the user signs to allow exactly these terms. Call Swap tokens before `authorization.expiresAt`.", "$ref": "#/components/schemas/MessageToSign" } }, "required": [ "terms", "quotedReceivedRaw", "quoteExpiresAt", "requestKey", "authorization" ], "description": "A priced swap, the message the user signs for it, and the key to send it with." }, "SwapTerms": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. It stays in the agent wallet." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the swap may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet receives of the bought asset, in its smallest unit." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "maxValueLossBps", "minimumReceivedRaw" ], "description": "The exact terms of a swap in the agent wallet: what it sells, what it buys, and the limits it must stay within." }, "MessageToSign": { "type": "object", "properties": { "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "message", "controllerId", "expiresAt" ], "description": "A message for the user to sign with their registered wallet or passkey, and the values to send back with the signature." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Swap tokens 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. `POST /v1/users/{userId}/wallet/swaps` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The quote's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same swap back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapTokensInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/swaps' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' \ --header 'Content-Type: application/json' \ --data '{ "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "minimumReceivedRaw": "331250000000000000000000", "maxValueLossBps": 250 }, "authorization": { "controllerId": "ee79012b-d19c-44f8-aef8-828b88142809", "expiresAt": "2026-09-22T18:04:30.000Z", "signature": { "kind": "evm", "signature": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" } } }' ``` ## Responses ### 200 The swap and its current status. Example response ```json { "id": "0d7a9d4e-1f53-4f3b-9d25-1c4e5f8b7a61", "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "minimumReceivedRaw": "331250000000000000000000", "maxValueLossBps": 250 }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ``` ```json { "description": "The swap and its current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swap" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `asset_not_swappable` — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off - `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_swappable` — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `swap_changed` — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `swap_changed` — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.swap", "summary": "Swap tokens", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapTokensInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The quote's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same swap back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The swap and its current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swap" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_swappable` — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `agent_slippage_exceeded` — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `swap_changed` — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "SwapTokensInput": { "type": "object", "properties": { "terms": { "description": "The quote's `terms`, unchanged.", "$ref": "#/components/schemas/SwapTermsInput" }, "authorization": { "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false, "description": "The user's signature of the quote's `authorization.message`, with its `controllerId` and `expiresAt` unchanged. Checked on arrival and never stored." }, "context": { "description": "What your app knows about the user as they make this request. A swap of a tokenized stock needs `context.country` again here: it applies to this request only, and a retry that finds its swap needs none.", "type": "object", "properties": { "country": { "description": "The country the user is making this request from, as an uppercase ISO 3166-1 alpha-2 code such as `GB`, resolved by your server from the request (your edge's IP geolocation), never taken from the browser. A tokenized stock is traded only when this reports a country where it is available.", "type": "string", "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false } }, "required": [ "terms", "authorization" ], "additionalProperties": false, "examples": [ { "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "minimumReceivedRaw": "331250000000000000000000", "maxValueLossBps": 250 }, "authorization": { "controllerId": "ee79012b-d19c-44f8-aef8-828b88142809", "expiresAt": "2026-09-22T18:04:30.000Z", "signature": { "kind": "evm", "signature": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" } } } ], "description": "A quoted swap and the user's signature allowing it." }, "SwapTermsInput": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. It stays in the agent wallet." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the swap may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet receives of the bought asset, in its smallest unit." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "maxValueLossBps", "minimumReceivedRaw" ], "additionalProperties": false, "description": "The exact terms of a swap in the agent wallet: what it sells, what it buys, and the limits it must stay within." }, "Swap": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id." }, "terms": { "description": "The terms the user signed.", "$ref": "#/components/schemas/SwapTerms" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, `processing` while it runs, then `completed` (the bought asset is in the agent wallet), `refunded` (the provider sent the sold asset back to the agent wallet) 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. `completed`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount when the swap started. `quote_rejected`: the price at execution failed its checks, or would have received less than `terms.minimumReceivedRaw` or lost more than the loss limit. `quote_expired`: the quote ran out before the provider took the swap. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the signature no longer covered it when it started. `stopped`: an operator paused trading or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign trades. In every case nothing was swapped; get a new quote to try again." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the swap was requested." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the swap started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; `null` before then." }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The provider swap's id." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based position in the swap's plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset it delivered: the bought asset, or the sold one when it was refunded." }, "amountRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The amount actually received (or refunded), in this asset's smallest unit; `null` until a receipt confirms it." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "The number of decimals of this asset's smallest unit." }, "intentHashes": { "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The NEAR Intents ids of the intents that carried out this step, as 1Click reported them when it settled. Quote one to support to trace the step. They are on the confidential NEAR Intents ledger, which no public explorer shows. Empty until the step settles, and for a step that was refunded or did not run." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this swap's outcome was observed." } }, "required": [ "id", "index", "state", "assetId", "amountRaw", "decimals", "intentHashes", "refundReason", "observedAt" ] }, "description": "The swap the provider made and what it delivered, as evidence." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the swap sold (`terms.amountRaw`) was worth when it ran, at the trusted price Fin checked its plan against. `null` before it has a plan, and when no price was recorded." } }, "required": [ "id", "terms", "status", "failureReason", "result", "createdAt", "startedAt", "reportedAt", "receipts", "value" ], "examples": [ { "id": "0d7a9d4e-1f53-4f3b-9d25-1c4e5f8b7a61", "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "minimumReceivedRaw": "331250000000000000000000", "maxValueLossBps": 250 }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ], "description": "A swap in the agent wallet: its terms, its `status`, and the evidence behind it." }, "SwapTerms": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. It stays in the agent wallet." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the swap may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet receives of the bought asset, in its smallest unit." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "maxValueLossBps", "minimumReceivedRaw" ], "description": "The exact terms of a swap in the agent wallet: what it sells, what it buys, and the limits it must stay within." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List swaps 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 /v1/users/{userId}/wallet/swaps` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "requestKey", "required": false, "description": "Only the swap sent with this `Idempotency-Key`: how to find it after a request timed out." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/swaps' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of swaps. ```json { "description": "A page of swaps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Swap" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.listSwaps", "summary": "List swaps", "tags": [ "wallets" ], "description": "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`.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "requestKey", "required": false, "description": "Only the swap sent with this `Idempotency-Key`: how to find it after a request timed out." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of swaps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Swap" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Swap": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id." }, "terms": { "description": "The terms the user signed.", "$ref": "#/components/schemas/SwapTerms" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, `processing` while it runs, then `completed` (the bought asset is in the agent wallet), `refunded` (the provider sent the sold asset back to the agent wallet) 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. `completed`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount when the swap started. `quote_rejected`: the price at execution failed its checks, or would have received less than `terms.minimumReceivedRaw` or lost more than the loss limit. `quote_expired`: the quote ran out before the provider took the swap. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the signature no longer covered it when it started. `stopped`: an operator paused trading or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign trades. In every case nothing was swapped; get a new quote to try again." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the swap was requested." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the swap started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; `null` before then." }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The provider swap's id." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based position in the swap's plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset it delivered: the bought asset, or the sold one when it was refunded." }, "amountRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The amount actually received (or refunded), in this asset's smallest unit; `null` until a receipt confirms it." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "The number of decimals of this asset's smallest unit." }, "intentHashes": { "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The NEAR Intents ids of the intents that carried out this step, as 1Click reported them when it settled. Quote one to support to trace the step. They are on the confidential NEAR Intents ledger, which no public explorer shows. Empty until the step settles, and for a step that was refunded or did not run." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this swap's outcome was observed." } }, "required": [ "id", "index", "state", "assetId", "amountRaw", "decimals", "intentHashes", "refundReason", "observedAt" ] }, "description": "The swap the provider made and what it delivered, as evidence." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the swap sold (`terms.amountRaw`) was worth when it ran, at the trusted price Fin checked its plan against. `null` before it has a plan, and when no price was recorded." } }, "required": [ "id", "terms", "status", "failureReason", "result", "createdAt", "startedAt", "reportedAt", "receipts", "value" ], "examples": [ { "id": "0d7a9d4e-1f53-4f3b-9d25-1c4e5f8b7a61", "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "minimumReceivedRaw": "331250000000000000000000", "maxValueLossBps": 250 }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ], "description": "A swap in the agent wallet: its terms, its `status`, and the evidence behind it." }, "SwapTerms": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. It stays in the agent wallet." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the swap may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet receives of the bought asset, in its smallest unit." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "maxValueLossBps", "minimumReceivedRaw" ], "description": "The exact terms of a swap in the agent wallet: what it sells, what it buys, and the limits it must stay within." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a swap 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. `GET /v1/users/{userId}/wallet/swaps/{swapId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "swapId", "required": true, "description": "The swap's id, as Swap tokens returned it." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/swaps/YOUR_SWAP_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The swap and its status. Example response ```json { "id": "0d7a9d4e-1f53-4f3b-9d25-1c4e5f8b7a61", "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "minimumReceivedRaw": "331250000000000000000000", "maxValueLossBps": 250 }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ``` ```json { "description": "The swap and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swap" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getSwap", "summary": "Get a swap", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "swapId", "required": true, "description": "The swap's id, as Swap tokens returned it." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The swap and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swap" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Swap": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id." }, "terms": { "description": "The terms the user signed.", "$ref": "#/components/schemas/SwapTerms" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, `processing` while it runs, then `completed` (the bought asset is in the agent wallet), `refunded` (the provider sent the sold asset back to the agent wallet) 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. `completed`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount when the swap started. `quote_rejected`: the price at execution failed its checks, or would have received less than `terms.minimumReceivedRaw` or lost more than the loss limit. `quote_expired`: the quote ran out before the provider took the swap. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the signature no longer covered it when it started. `stopped`: an operator paused trading or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign trades. In every case nothing was swapped; get a new quote to try again." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the swap was requested." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the swap started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; `null` before then." }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The provider swap's id." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based position in the swap's plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset it delivered: the bought asset, or the sold one when it was refunded." }, "amountRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The amount actually received (or refunded), in this asset's smallest unit; `null` until a receipt confirms it." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "The number of decimals of this asset's smallest unit." }, "intentHashes": { "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The NEAR Intents ids of the intents that carried out this step, as 1Click reported them when it settled. Quote one to support to trace the step. They are on the confidential NEAR Intents ledger, which no public explorer shows. Empty until the step settles, and for a step that was refunded or did not run." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this swap's outcome was observed." } }, "required": [ "id", "index", "state", "assetId", "amountRaw", "decimals", "intentHashes", "refundReason", "observedAt" ] }, "description": "The swap the provider made and what it delivered, as evidence." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the swap sold (`terms.amountRaw`) was worth when it ran, at the trusted price Fin checked its plan against. `null` before it has a plan, and when no price was recorded." } }, "required": [ "id", "terms", "status", "failureReason", "result", "createdAt", "startedAt", "reportedAt", "receipts", "value" ], "examples": [ { "id": "0d7a9d4e-1f53-4f3b-9d25-1c4e5f8b7a61", "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "minimumReceivedRaw": "331250000000000000000000", "maxValueLossBps": 250 }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ], "description": "A swap in the agent wallet: its terms, its `status`, and the evidence behind it." }, "SwapTerms": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. It stays in the agent wallet." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the swap may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet receives of the bought asset, in its smallest unit." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "maxValueLossBps", "minimumReceivedRaw" ], "description": "The exact terms of a swap in the agent wallet: what it sells, what it buys, and the limits it must stay within." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Read current remaining actions 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. `GET /v1/users/{userId}/wallet/trades/{tradeId}/remaining-actions` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tradeId", "required": true, "description": "The trade's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/trades/YOUR_TRADE_ID/remaining-actions' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 Current recovery candidates for this owned trade. ```json { "description": "Current recovery candidates for this owned trade.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "candidates": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15 }, "kind": { "type": "string", "enum": [ "unclaimed", "refunded", "not_executed" ] } }, "required": [ "index", "kind" ] } } }, "required": [ "operationId", "candidates" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getRemainingTradeActions", "summary": "Read current remaining actions", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tradeId", "required": true, "description": "The trade's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "Current recovery candidates for this owned trade.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "candidates": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15 }, "kind": { "type": "string", "enum": [ "unclaimed", "refunded", "not_executed" ] } }, "required": [ "index", "kind" ] } } }, "required": [ "operationId", "candidates" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Review remaining actions 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. `POST /v1/users/{userId}/wallet/trades/{tradeId}/remaining-proposal` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tradeId", "required": true, "description": "The trade's id." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": false, "description": "A UUID for this fresh review intent. Retry the same key and body to get its original proposal; a changed body is refused. Choose a new key for a new review after a prior review closes. Without a key, matching active or claimed selections retain the older replay behavior." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "originalIndices": { "description": "Original frozen plan positions, zero-based. Omit to review every eligible unfinished branch. A selected failed node includes its unfinished dependencies and descendants. A prior claim is eligible only with conclusive not-executed or final-refund evidence; settled or unresolved claims cannot be replaced. The new proposal rechecks current funds and requires fresh approval.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "maxValueLossBps": { "description": "An explicitly chosen all-in loss limit for the new review, in basis points as an integer string. It must be at least the original limit. A higher limit replaces only the original derived price floor; an explicitly requested minimum receive remains enforced. The returned approval still needs the user's signature.", "type": "string" } }, "additionalProperties": false } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/trades/YOUR_TRADE_ID/remaining-proposal' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data '{}' ``` ## Responses ### 202 The complete remaining-action proposal and its fresh approval run. ```json { "description": "The complete remaining-action proposal and its fresh approval run.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "originalTradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "originalIndices": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "fingerprint": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "request": { "type": "object", "properties": { "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Exchange one asset for another; custody never leaves the agent wallet.", "enum": [ "swap" ] }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Return an asset to the account that owns the agent wallet.", "enum": [ "withdraw_to_owner" ] }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route.", "enum": [ "withdraw_transfer" ] }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] } ] }, "description": "The complete ordered financial actions proposed for this execution, with concrete assets and exact quantity rules." }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The explicit loss and signature-lifetime limits; these must exactly match the approved grant." }, "execution": { "description": "Required on every new chat proposal: the exact execution limits proposed for approval. Copy existing signed grants unchanged; historical approvals and standing grants with this field omitted retain their original execution behavior.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dependency_graph" ] }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "actions", "bounds" ] }, "run": { "$ref": "#/components/schemas/Run" } }, "required": [ "proposalId", "originalTradeId", "originalIndices", "fingerprint", "expiresAt", "request", "run" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `trade_not_recoverable` — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request - `run_active` — a run already holds this conversation ```json { "description": "The operation lost to the current state.\n\n- `trade_not_recoverable` — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `run_active` — a run already holds this conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 410 The resource still exists and stays readable, but can no longer take this request. - `conversation_deleted` — the conversation was deleted; its history stays readable ```json { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `conversation_deleted` — the conversation was deleted; its history stays readable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it - `execution_capacity` — no capacity is free to run this right now; honour `Retry-After` - `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again - `deployment_paused` — an operator paused this kind of work for the deployment; try again later ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `deployment_paused` — an operator paused this kind of work for the deployment; try again later", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.prepareRemainingTrade", "summary": "Review remaining actions", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "originalIndices": { "description": "Original frozen plan positions, zero-based. Omit to review every eligible unfinished branch. A selected failed node includes its unfinished dependencies and descendants. A prior claim is eligible only with conclusive not-executed or final-refund evidence; settled or unresolved claims cannot be replaced. The new proposal rechecks current funds and requires fresh approval.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "maxValueLossBps": { "description": "An explicitly chosen all-in loss limit for the new review, in basis points as an integer string. It must be at least the original limit. A higher limit replaces only the original derived price floor; an explicitly requested minimum receive remains enforced. The returned approval still needs the user's signature.", "type": "string" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tradeId", "required": true, "description": "The trade's id." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": false, "description": "A UUID for this fresh review intent. Retry the same key and body to get its original proposal; a changed body is refused. Choose a new key for a new review after a prior review closes. Without a key, matching active or claimed selections retain the older replay behavior." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "202": { "description": "The complete remaining-action proposal and its fresh approval run.", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "originalTradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "originalIndices": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "fingerprint": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "request": { "type": "object", "properties": { "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Exchange one asset for another; custody never leaves the agent wallet.", "enum": [ "swap" ] }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Return an asset to the account that owns the agent wallet.", "enum": [ "withdraw_to_owner" ] }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route.", "enum": [ "withdraw_transfer" ] }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] } ] }, "description": "The complete ordered financial actions proposed for this execution, with concrete assets and exact quantity rules." }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The explicit loss and signature-lifetime limits; these must exactly match the approved grant." }, "execution": { "description": "Required on every new chat proposal: the exact execution limits proposed for approval. Copy existing signed grants unchanged; historical approvals and standing grants with this field omitted retain their original execution behavior.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dependency_graph" ] }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "actions", "bounds" ] }, "run": { "$ref": "#/components/schemas/Run" } }, "required": [ "proposalId", "originalTradeId", "originalIndices", "fingerprint", "expiresAt", "request", "run" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `trade_not_recoverable` — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `run_active` — a run already holds this conversation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "410": { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `conversation_deleted` — the conversation was deleted; its history stays readable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `execution_capacity` — no capacity is free to run this right now; honour `Retry-After`\n- `partner_run_capacity` — this partner's active run quota is full; honour Retry-After and reuse the same request identity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `execution_unavailable` — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `deployment_paused` — an operator paused this kind of work for the deployment; try again later", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "Run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id. It stays the same while the run pauses for approvals and resumes." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "input": { "description": "The user's message that started the run; null only for old runs that did not keep it.", "type": [ "string", "null" ] }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "Meaning of this terminal output contract.", "type": "string", "maxLength": 4096 }, "schema": { "description": "The immutable strict object schema that the terminal output must satisfy.", "$ref": "#/components/schemas/RunOutputObjectSchema" } }, "required": [ "name", "schema" ], "description": "The immutable admitted output contract, readable without invoking its admission transform." }, "modelId": { "description": "The reviewed provider model pinned by trusted admission; absent for historical default selection.", "type": "string", "minLength": 1, "maxLength": 200 } }, "description": "The tools, output contract and model the run started with. They never change." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the run started." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the run ended; null while it is running or paused for human input or approval." }, "status": { "$ref": "#/components/schemas/RunStatus" }, "output": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "null" } ], "description": "The run's terminal structured result, once it has one under its `outputContract`; null otherwise." }, "response": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "description": "The agent's full reply, never shortened." }, "eventSeq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The `seq` of the event that carries the reply." }, "completeness": { "type": "string", "enum": [ "complete", "partial" ], "description": "`complete` when the run completed; `partial` when it was stopped or failed before finishing." } }, "required": [ "text", "eventSeq", "completeness" ] }, { "type": "null" } ], "description": "The agent's reply since the run last started, resumed or was steered, once it has one." }, "error": { "description": "Why the run failed or was stopped; null when neither happened.", "type": [ "string", "null" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "model_timeout", "model_invalid_output", "execution_deadline", "provider_rate_limit", "provider_unavailable", "provider_authentication", "internal_error", "context_too_large", "daily_budget_exhausted", "monthly_budget_exhausted", "budget_frozen", "partner_daily_budget_exhausted", "partner_monthly_budget_exhausted", "unknown" ], "description": "Why the execution failed: `model_timeout` (the model was too slow to respond), `execution_deadline` (the run's active time limit elapsed before it finished), `provider_rate_limit` or `provider_unavailable` (classified from HTTP status or a connection/body-read failure observed by the host), `model_invalid_output` (terminal structured output still failed its required format after bounded repair), `context_too_large` (the request stayed over the model's context window after the host condensed earlier history and retried once), `daily_budget_exhausted`, `monthly_budget_exhausted` or `budget_frozen` (the user's AI budget for the UTC day or month, or an operator's freeze on it, left no room for the run's next model request), `partner_daily_budget_exhausted` or `partner_monthly_budget_exhausted` (the partner account's AI spend limit for the UTC day or month left no room for it), `internal_error` (a host-side fault), or `unknown` when nothing more specific was classified. A budget or spend-limit code means a limit stopped the run, not that the model failed; trying again fails the same way until the limit clears. A raised user budget or a lifted freeze applies at once; a raised partner limit applies from the next UTC day or month, because the open period keeps the cap it started with." }, "stage": { "type": "string", "enum": [ "model_request", "tool_execution", "finalization" ], "description": "Which phase of the run was executing when it failed: `model_request` while calling or awaiting the model provider, `tool_execution` while running or resuming a tool call, or `finalization` while settling the run's output and accounting after the model finished." }, "providerMessage": { "description": "The model provider's own error text, when one was available: credential values are redacted and it is cut to 256 characters, but it is not a content classifier, so other sensitive detail may remain. Treat it as diagnostic context only — never branch on it, and review before showing it to an end user.", "type": "string", "minLength": 1, "maxLength": 256 }, "diagnosticReference": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This failed run's own id, repeated here as one field to cite when asking support to check the host's internal logs for this execution; it carries no meaning beyond that." }, "effectWarning": { "type": "string", "const": "Earlier actions may have completed. Partial output does not prove success or a delivery failure. Check receipts before retrying; retrying may repeat actions.", "description": "This build's fixed caution: earlier actions may already have run, so partial output alone never proves success, a delivery failure, or that retrying is free of duplicate effects." } }, "required": [ "code", "stage", "diagnosticReference", "effectWarning" ] }, { "type": "null" } ], "description": "Details of a failure, when recorded." }, "pendingApprovals": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "description": "The approvals this run is waiting on, oldest first." }, "pendingQuestions": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The questionnaire ids this run is waiting on, oldest first." }, "steers": { "type": "array", "items": { "$ref": "#/components/schemas/RunSteer" }, "description": "The messages the user sent this run while it worked, with Steer a run, oldest first; empty when they sent none." }, "feedback": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedback" }, { "type": "null" } ], "description": "The user's feedback on this run's reply; null until they send it." }, "origin": { "anyOf": [ { "type": "object", "properties": { "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run it carried out: its `id` in List an automation's runs." }, "name": { "type": "string", "description": "The automation's name when that automation run was recorded." } }, "required": [ "automationId", "automationRunId", "name" ] }, { "type": "null" } ], "description": "The automation that started this run; `null` for a run the user started with a message." }, "reads": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "account", "prices" ] }, "description": "What the agent read while it worked, told by the tools whose calls completed: `account` (the user's own balances, holdings, orders or positions) and `prices` (market prices). Empty when it read neither." } }, "required": [ "id", "conversationId", "input", "profile", "startedAt", "endedAt", "status", "output", "response", "error", "failure", "pendingApprovals", "pendingQuestions", "steers", "feedback", "origin", "reads" ], "description": "The agent's work on one message: its status, the agent's reply once it finishes, any approvals or questionnaires it is waiting on, the messages the user sent it while it worked, and the user's feedback on the reply." }, "RunOutputObjectSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "JSON Schema type keyword: object." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/RunOutputSchemaNode" }, "description": "Named fields and their strict schemas." }, "required": { "type": "array", "items": { "type": "string" }, "description": "Every declared property is required exactly once." }, "additionalProperties": { "type": "boolean", "const": false, "description": "Always false; undeclared properties are rejected." } }, "required": [ "type", "properties", "required", "additionalProperties" ], "description": "A strict object with all declared properties required and no extra properties." }, "RunOutputSchemaNode": { "description": "A bounded node in the strict JSON Schema supported for run output.", "$ref": "#/components/schemas/schema0" }, "schema0": { "anyOf": [ { "$ref": "#/components/schemas/RunOutputObjectSchema" }, { "type": "object", "properties": { "type": { "type": "string", "const": "array", "description": "JSON Schema type keyword: array." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "items": { "description": "Schema every array entry must satisfy.", "$ref": "#/components/schemas/RunOutputSchemaNode" }, "minItems": { "description": "Inclusive minimum number of array entries.", "type": "number" }, "maxItems": { "description": "Inclusive maximum number of array entries.", "type": "number" } }, "required": [ "type", "items" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "JSON Schema type keyword: string." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "string" } }, "minLength": { "description": "Inclusive minimum string length.", "type": "number" }, "maxLength": { "description": "Inclusive maximum string length.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "number", "description": "JSON Schema type keyword: number." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "JSON Schema type keyword: integer." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "number" } }, "minimum": { "description": "Inclusive numeric lower bound.", "type": "number" }, "maximum": { "description": "Inclusive numeric upper bound.", "type": "number" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "JSON Schema type keyword: boolean." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" }, "enum": { "description": "The allowed literal values, when restricted.", "type": "array", "items": { "type": "boolean" } } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "null", "description": "JSON Schema type keyword: null." }, "description": { "description": "Human-readable meaning of this schema node.", "type": "string" } }, "required": [ "type" ] } ], "description": "One supported strict JSON Schema node: object, array, string, number, integer, boolean or null." }, "RunStatus": { "type": "string", "enum": [ "running", "completed", "aborted", "failed", "paused" ], "description": "What the run is doing: `running`, or how it stopped — `completed` or `failed` once the model finished, `aborted` when stopped early, or `paused` while an approval is pending." }, "JsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "RunSteer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The message's id; the `run.steered` event that delivers it names it." }, "text": { "type": "string", "description": "The message, as the user sent it." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dropped" ], "description": "`pending` until the agent reads it at its next step; `delivered` once it has; `dropped` when the run ended before the agent read it, so it was never acted on. Send a dropped message again with Start a run." }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user sent it." }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the agent read it; null until it is `delivered`." } }, "required": [ "id", "text", "status", "sentAt", "deliveredAt" ], "description": "A message the user sent a run while it was working, and whether the agent read it." }, "RunFeedback": { "type": "object", "properties": { "rating": { "$ref": "#/components/schemas/RunFeedbackRating" }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/RunFeedbackReason" }, { "type": "null" } ], "description": "Why the user rated it down; null when they gave no reason or rated it `up`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the user first sent feedback on this run's reply." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the feedback last changed; the same as `createdAt` until it does." } }, "required": [ "rating", "reason", "createdAt", "updatedAt" ], "description": "The user's feedback on one run's reply: a thumbs-up or thumbs-down, and why." }, "RunFeedbackRating": { "type": "string", "enum": [ "up", "down" ], "description": "How the user rated the reply: `up` for a thumbs-up, `down` for a thumbs-down." }, "RunFeedbackReason": { "type": "string", "enum": [ "wrong", "unhelpful", "slow", "unsafe", "other" ], "description": "Why the user rated the reply down: `wrong` it was incorrect, `unhelpful` it did not do what was asked, `slow` it took too long, `unsafe` it was risky or inappropriate, `other` none of these." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List trades Lists the trades the agent made or proposed, newest first, each with its `status` and receipts. Filter by `runId` or `conversationId`. `GET /v1/users/{userId}/wallet/trades` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "runId", "required": false, "description": "Only trades proposed by this agent run." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "conversationId", "required": false, "description": "Only trades proposed in this conversation." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/trades' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of trades. ```json { "description": "A page of trades.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WalletTrade" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.listTrades", "summary": "List trades", "tags": [ "wallets" ], "description": "Lists the trades the agent made or proposed, newest first, each with its `status` and receipts. Filter by `runId` or `conversationId`.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "runId", "required": false, "description": "Only trades proposed by this agent run." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "conversationId", "required": false, "description": "Only trades proposed in this conversation." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of trades.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WalletTrade" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "WalletTrade": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id." }, "source": { "type": "object", "properties": { "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The proposing conversation, or null when historical lineage was not retained." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id. It stays the same while the run pauses for approvals and resumes." }, { "type": "null" } ], "description": "The proposing stable agent run, or null when historical lineage was not retained." }, "callId": { "description": "The recorded proposing model tool call, or null when historical lineage was not retained.", "type": [ "string", "null" ] }, "automationRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The automation run that started the proposing run, or null when an automation did not start it." } }, "required": [ "conversationId", "runId", "callId", "automationRunId" ], "description": "Where the trade came from: the conversation, run and tool call that proposed it, and the automation run behind it, if any. None of them is consent." }, "request": { "anyOf": [ { "type": "object", "properties": { "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] } ] }, "description": "The complete ordered financial actions proposed for this execution, with concrete assets and exact quantity rules." }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The explicit loss and signature-lifetime limits; these must exactly match the approved grant." }, "execution": { "description": "Required on every new chat proposal: the exact execution limits proposed for approval. Copy existing signed grants unchanged; historical approvals and standing grants with this field omitted retain their original execution behavior.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "actions", "bounds" ] }, { "type": "null" } ], "description": "What the agent asked for: the actions and their limits, as swaps and payouts to the destination the user approved. A refused proposal is shown with its refusal. `null` only for old trades recorded without it." }, "approval": { "type": "object", "properties": { "request": { "anyOf": [ { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval of this exact trade request." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The recorded review decision; overdue pending reviews are presented as expired." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this review cannot authorize execution." }, "contract": { "description": "The exact reviewed financial terms, when retained and readable.", "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, "executionRestriction": { "description": "Present when the reviewed request was forbidden from signing or moving funds.", "type": "string", "const": "signing_disabled" } }, "required": [ "approvalId", "status", "expiresAt" ] }, { "type": "null" } ], "description": "The exact request's retained review; null when standing consent supplied authority." }, "grantApprovalId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The approval that created the immutable grant used by this trade, if bound." } }, "required": [ "request", "grantApprovalId" ], "description": "Who approved the trade: the approval of this request, or the standing approval it ran under." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "partial", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, usually while it waits for the user's approval. `processing` while it runs, or while a swap it sent waits for the provider to confirm it. Then `completed` (every swap settled, or there was nothing to swap: `outcome.status` is `no_trade`), `partial` (some swaps settled and a later one did not; the settled swaps stand), `refunded` (the provider sent the funds back to the agent wallet) or `failed` (nothing was swapped; `failureReason` says why). `denied` and `expired` mean the user denied it, or its approval ran out, before it started. `uncertain` means the result could not be confirmed yet: never ask the agent for a replacement, keep checking. `completed`, `partial`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the agent wallet did not hold enough when the trade started. `quote_rejected`: the price or transfer at execution failed its checks or fell outside the approved limits. `quote_expired`: the quote ran out before the provider took the swap. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the approval did not cover it when it started (it asked for something else, or the approval had expired or used up its limits), or nothing could sign it then (the automation firing it ran for was not confirmed in time, or is no longer current). `stopped`: an operator paused trading, stopped the automation or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign trades. In every case nothing was swapped." }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do. On a `partial` trade, `outcome.stopped` names the swap it stopped on when that swap never started." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the trade was proposed." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the trade started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; settlement can still follow." }, "plan": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The frozen trade execution plan identity." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the trade execution terms were frozen." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this plan cannot authorize new signing." }, "legs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input", "description": "Spends the fixed input amount and requires at least minimumOutputRaw in return." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the original requested action this leg implements." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the asset's smallest unit as an integer string." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "The pinned input asset and exact amount this leg may spend." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The pinned asset this leg must receive." }, "minimumOutputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The minimum acceptable output amount, in the output asset's smallest unit as an integer string." }, "referenceOutputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The reference output amount from trusted price evidence before applying the approved loss bound, in the output asset's smallest unit." }, "inputPriceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "Enforcement's own trusted USD price per whole token at plan freeze, as plain decimal text." }, "outputPriceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "Enforcement's own trusted USD price per whole token at plan freeze, as plain decimal text." } }, "required": [ "kind", "index", "actionIndex", "input", "output", "minimumOutputRaw", "referenceOutputRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output", "description": "Receives the fixed output amount and spends no more than maximumInputRaw." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the original requested action this leg implements." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The pinned asset this leg may spend." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the asset's smallest unit as an integer string." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "The pinned output asset and exact amount this leg must receive." }, "maximumInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The maximum permitted input amount, in the input asset's smallest unit as an integer string." }, "referenceInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The reference input amount from trusted price evidence before applying the approved loss bound, in the input asset's smallest unit." }, "inputPriceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "Enforcement's own trusted USD price per whole token at plan freeze, as plain decimal text." }, "outputPriceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "Enforcement's own trusted USD price per whole token at plan freeze, as plain decimal text." } }, "required": [ "kind", "index", "actionIndex", "input", "output", "maximumInputRaw", "referenceInputRaw" ] } ] }, "description": "Every frozen planned leg, including unattempted legs." } }, "required": [ "id", "createdAt", "expiresAt", "legs" ] }, { "type": "null" } ], "description": "The steps the trade planned, fixed before signing, or `null` before there is a plan. A planned step is not proof it ran." }, "legs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The durable claim identity for this actually attempted trade leg." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "This actual leg position in the frozen plan, counting from zero." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "inputToken": { "description": "The input asset id this leg claimed, or null on a leg claimed before the trade record was stored.", "type": [ "string", "null" ] }, "outputToken": { "description": "The output asset id this leg claimed, or null on a leg claimed before the trade record was stored.", "type": [ "string", "null" ] }, "debitRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The exact input the signed transfer debits, in the input asset's smallest unit as an integer string. Null when not recorded." }, "quoteOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The verified provider quote's reported output, in the output asset's smallest unit as an integer string. Null when not recorded." }, "settledOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The settled output amount the database derived from the verified receipt, in the output asset's smallest unit as an integer string, or null when the leg is not settled or its settlement carried no amount." }, "minimumOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The frozen minimum output of an exact-input leg, or null for an exact-output leg or an unrecorded claim." }, "maximumInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The frozen maximum input of an exact-output leg, or null for an exact-input leg or an unrecorded claim." }, "inputPriceUsd": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "Enforcement's own trusted USD price per whole input token at plan freeze, or null when unknown. Valuation evidence." }, "outputPriceUsd": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "Enforcement's own trusted USD price per whole output token at plan freeze, or null when unknown. Valuation evidence." }, "pricesObservedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "The oldest trusted market observation time the frozen prices came from, or null when unknown." }, "inputValueUsdAtPlan": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The debit valued at the trusted plan-freeze input price, truncated to cents, or null when the debit or price is unknown. Derived on read, never stored." }, "outputValueUsdAtPlan": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The settled output valued at the trusted plan-freeze output price, truncated to cents, or null when the settled amount or price is unknown. Derived on read, never stored." }, "quoteInputUsd": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The provider's own reported USD value of the input: provider-reported, untrusted, display only, or null when absent or malformed." }, "quoteOutputUsd": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The provider's own reported USD value of the output: provider-reported, untrusted, display only, or null when absent or malformed." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this trade execution leg was claimed." }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this leg signature was durably recorded; null before signing." }, "settledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this leg terminal resolution was recorded, or null while unresolved; inspect its receipt for the resolution kind." }, "receipt": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "state": { "type": "string", "const": "settled", "description": "The leg settled: its output asset moved as planned." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What the leg produced." } }, "required": [ "approvalId", "legId", "index", "state", "output" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "state": { "type": "string", "const": "refunded", "description": "The leg did not settle and its input asset was returned." }, "refund": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What was returned." } }, "required": [ "approvalId", "legId", "index", "state", "refund" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "state": { "type": "string", "const": "not_executed", "description": "The leg did not settle. Most reasons mean it never reached the provider; `rejected` means it did and was refused there — see `reason`." }, "reason": { "description": "Why nothing executed: `signing_disabled` when automatic signing was off, `signing_failed` when signing itself failed, `rejected` when the provider refused the submission outright (it did reach the provider), `expired` when the leg's own signing/deposit window elapsed before a terminal fact arrived, or `failed` otherwise. Optional so receipts written before the reason was carried still parse.", "type": "string", "enum": [ "signing_disabled", "signing_failed", "rejected", "expired", "failed" ] }, "unsignedBy": { "description": "Present with `signing_failed` on an Agent API wallet's leg when the NEAR Intents Agent API, the wallet's signer, released no signature for it: it refused the request, or its own history proves it released none. Nothing moved.", "type": "string", "const": "agent_api" } }, "required": [ "approvalId", "legId", "index", "state" ] } ] }, { "type": "null" } ], "description": "The complete verified public settlement, refund or non-execution evidence, or null while unresolved." }, "transferPayout": { "anyOf": [ { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "transactionHashes": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Destination chain transactions, or the funding intent identifiers binding the provider-confirmed ledger payout." }, "quotedFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Withdrawal fee in destination-asset units from the bound signed quote, or null when not disclosed. Actual received amount is recorded separately." } }, "required": [ "rail", "network", "address", "transactionHashes", "quotedFeeRaw" ] }, { "type": "null" } ], "description": "For a step that paid an address the user approved: where the payout landed and its transaction ids, as a withdrawal's receipt shows them. `null` for a swap, a payout to the user's main wallet, a step that has not settled, or an older trade." }, "intentHashes": { "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The NEAR Intents ids of the intents that carried out this step, as 1Click reported them when it settled. Quote one to support to trace the step. They are on the confidential NEAR Intents ledger, which no public explorer shows. Empty until the step settles, and for a step that was refunded or did not run." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." } }, "required": [ "id", "index", "state", "inputToken", "outputToken", "debitRaw", "quoteOutputRaw", "settledOutputRaw", "minimumOutputRaw", "maximumInputRaw", "inputPriceUsd", "outputPriceUsd", "pricesObservedAt", "inputValueUsdAtPlan", "outputValueUsdAtPlan", "quoteInputUsd", "quoteOutputUsd", "createdAt", "signedAt", "settledAt", "receipt", "transferPayout", "intentHashes", "refundReason" ] }, "description": "The steps that actually ran, in plan order, each with its amounts and receipt. A planned step that never started has no entry." } }, "required": [ "id", "source", "request", "approval", "status", "failureReason", "outcome", "createdAt", "startedAt", "reportedAt", "plan", "legs" ], "description": "A trade the agent made or proposed from the agent wallet: what it asked for, who approved it, its `status`, and the plan it ran and the result of each step as evidence." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a trade 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. `GET /v1/users/{userId}/wallet/trades/{tradeId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tradeId", "required": true, "description": "The trade's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/trades/YOUR_TRADE_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The trade and its status. ```json { "description": "The trade and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTrade" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getTrade", "summary": "Get a trade", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "tradeId", "required": true, "description": "The trade's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The trade and its status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTrade" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "WalletTrade": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id." }, "source": { "type": "object", "properties": { "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The proposing conversation, or null when historical lineage was not retained." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id. It stays the same while the run pauses for approvals and resumes." }, { "type": "null" } ], "description": "The proposing stable agent run, or null when historical lineage was not retained." }, "callId": { "description": "The recorded proposing model tool call, or null when historical lineage was not retained.", "type": [ "string", "null" ] }, "automationRunId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The automation run that started the proposing run, or null when an automation did not start it." } }, "required": [ "conversationId", "runId", "callId", "automationRunId" ], "description": "Where the trade came from: the conversation, run and tool call that proposed it, and the automation run behind it, if any. None of them is consent." }, "request": { "anyOf": [ { "type": "object", "properties": { "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] } ] }, "description": "The complete ordered financial actions proposed for this execution, with concrete assets and exact quantity rules." }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The explicit loss and signature-lifetime limits; these must exactly match the approved grant." }, "execution": { "description": "Required on every new chat proposal: the exact execution limits proposed for approval. Copy existing signed grants unchanged; historical approvals and standing grants with this field omitted retain their original execution behavior.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "actions", "bounds" ] }, { "type": "null" } ], "description": "What the agent asked for: the actions and their limits, as swaps and payouts to the destination the user approved. A refused proposal is shown with its refusal. `null` only for old trades recorded without it." }, "approval": { "type": "object", "properties": { "request": { "anyOf": [ { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval of this exact trade request." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The recorded review decision; overdue pending reviews are presented as expired." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this review cannot authorize execution." }, "contract": { "description": "The exact reviewed financial terms, when retained and readable.", "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, "executionRestriction": { "description": "Present when the reviewed request was forbidden from signing or moving funds.", "type": "string", "const": "signing_disabled" } }, "required": [ "approvalId", "status", "expiresAt" ] }, { "type": "null" } ], "description": "The exact request's retained review; null when standing consent supplied authority." }, "grantApprovalId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The approval that created the immutable grant used by this trade, if bound." } }, "required": [ "request", "grantApprovalId" ], "description": "Who approved the trade: the approval of this request, or the standing approval it ran under." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "partial", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, usually while it waits for the user's approval. `processing` while it runs, or while a swap it sent waits for the provider to confirm it. Then `completed` (every swap settled, or there was nothing to swap: `outcome.status` is `no_trade`), `partial` (some swaps settled and a later one did not; the settled swaps stand), `refunded` (the provider sent the funds back to the agent wallet) or `failed` (nothing was swapped; `failureReason` says why). `denied` and `expired` mean the user denied it, or its approval ran out, before it started. `uncertain` means the result could not be confirmed yet: never ask the agent for a replacement, keep checking. `completed`, `partial`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the agent wallet did not hold enough when the trade started. `quote_rejected`: the price or transfer at execution failed its checks or fell outside the approved limits. `quote_expired`: the quote ran out before the provider took the swap. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the approval did not cover it when it started (it asked for something else, or the approval had expired or used up its limits), or nothing could sign it then (the automation firing it ran for was not confirmed in time, or is no longer current). `stopped`: an operator paused trading, stopped the automation or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign trades. In every case nothing was swapped." }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do. On a `partial` trade, `outcome.stopped` names the swap it stopped on when that swap never started." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the trade was proposed." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the trade started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; settlement can still follow." }, "plan": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The frozen trade execution plan identity." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the trade execution terms were frozen." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this plan cannot authorize new signing." }, "legs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input", "description": "Spends the fixed input amount and requires at least minimumOutputRaw in return." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the original requested action this leg implements." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the asset's smallest unit as an integer string." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "The pinned input asset and exact amount this leg may spend." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The pinned asset this leg must receive." }, "minimumOutputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The minimum acceptable output amount, in the output asset's smallest unit as an integer string." }, "referenceOutputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The reference output amount from trusted price evidence before applying the approved loss bound, in the output asset's smallest unit." }, "inputPriceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "Enforcement's own trusted USD price per whole token at plan freeze, as plain decimal text." }, "outputPriceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "Enforcement's own trusted USD price per whole token at plan freeze, as plain decimal text." } }, "required": [ "kind", "index", "actionIndex", "input", "output", "minimumOutputRaw", "referenceOutputRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output", "description": "Receives the fixed output amount and spends no more than maximumInputRaw." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the original requested action this leg implements." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The pinned asset this leg may spend." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the asset's smallest unit as an integer string." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "The pinned output asset and exact amount this leg must receive." }, "maximumInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The maximum permitted input amount, in the input asset's smallest unit as an integer string." }, "referenceInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The reference input amount from trusted price evidence before applying the approved loss bound, in the input asset's smallest unit." }, "inputPriceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "Enforcement's own trusted USD price per whole token at plan freeze, as plain decimal text." }, "outputPriceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "Enforcement's own trusted USD price per whole token at plan freeze, as plain decimal text." } }, "required": [ "kind", "index", "actionIndex", "input", "output", "maximumInputRaw", "referenceInputRaw" ] } ] }, "description": "Every frozen planned leg, including unattempted legs." } }, "required": [ "id", "createdAt", "expiresAt", "legs" ] }, { "type": "null" } ], "description": "The steps the trade planned, fixed before signing, or `null` before there is a plan. A planned step is not proof it ran." }, "legs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The durable claim identity for this actually attempted trade leg." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "This actual leg position in the frozen plan, counting from zero." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "inputToken": { "description": "The input asset id this leg claimed, or null on a leg claimed before the trade record was stored.", "type": [ "string", "null" ] }, "outputToken": { "description": "The output asset id this leg claimed, or null on a leg claimed before the trade record was stored.", "type": [ "string", "null" ] }, "debitRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The exact input the signed transfer debits, in the input asset's smallest unit as an integer string. Null when not recorded." }, "quoteOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The verified provider quote's reported output, in the output asset's smallest unit as an integer string. Null when not recorded." }, "settledOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The settled output amount the database derived from the verified receipt, in the output asset's smallest unit as an integer string, or null when the leg is not settled or its settlement carried no amount." }, "minimumOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The frozen minimum output of an exact-input leg, or null for an exact-output leg or an unrecorded claim." }, "maximumInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The frozen maximum input of an exact-output leg, or null for an exact-input leg or an unrecorded claim." }, "inputPriceUsd": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "Enforcement's own trusted USD price per whole input token at plan freeze, or null when unknown. Valuation evidence." }, "outputPriceUsd": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "Enforcement's own trusted USD price per whole output token at plan freeze, or null when unknown. Valuation evidence." }, "pricesObservedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "The oldest trusted market observation time the frozen prices came from, or null when unknown." }, "inputValueUsdAtPlan": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The debit valued at the trusted plan-freeze input price, truncated to cents, or null when the debit or price is unknown. Derived on read, never stored." }, "outputValueUsdAtPlan": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The settled output valued at the trusted plan-freeze output price, truncated to cents, or null when the settled amount or price is unknown. Derived on read, never stored." }, "quoteInputUsd": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The provider's own reported USD value of the input: provider-reported, untrusted, display only, or null when absent or malformed." }, "quoteOutputUsd": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "The provider's own reported USD value of the output: provider-reported, untrusted, display only, or null when absent or malformed." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this trade execution leg was claimed." }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this leg signature was durably recorded; null before signing." }, "settledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this leg terminal resolution was recorded, or null while unresolved; inspect its receipt for the resolution kind." }, "receipt": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "state": { "type": "string", "const": "settled", "description": "The leg settled: its output asset moved as planned." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What the leg produced." } }, "required": [ "approvalId", "legId", "index", "state", "output" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "state": { "type": "string", "const": "refunded", "description": "The leg did not settle and its input asset was returned." }, "refund": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What was returned." } }, "required": [ "approvalId", "legId", "index", "state", "refund" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "state": { "type": "string", "const": "not_executed", "description": "The leg did not settle. Most reasons mean it never reached the provider; `rejected` means it did and was refused there — see `reason`." }, "reason": { "description": "Why nothing executed: `signing_disabled` when automatic signing was off, `signing_failed` when signing itself failed, `rejected` when the provider refused the submission outright (it did reach the provider), `expired` when the leg's own signing/deposit window elapsed before a terminal fact arrived, or `failed` otherwise. Optional so receipts written before the reason was carried still parse.", "type": "string", "enum": [ "signing_disabled", "signing_failed", "rejected", "expired", "failed" ] }, "unsignedBy": { "description": "Present with `signing_failed` on an Agent API wallet's leg when the NEAR Intents Agent API, the wallet's signer, released no signature for it: it refused the request, or its own history proves it released none. Nothing moved.", "type": "string", "const": "agent_api" } }, "required": [ "approvalId", "legId", "index", "state" ] } ] }, { "type": "null" } ], "description": "The complete verified public settlement, refund or non-execution evidence, or null while unresolved." }, "transferPayout": { "anyOf": [ { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "transactionHashes": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Destination chain transactions, or the funding intent identifiers binding the provider-confirmed ledger payout." }, "quotedFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Withdrawal fee in destination-asset units from the bound signed quote, or null when not disclosed. Actual received amount is recorded separately." } }, "required": [ "rail", "network", "address", "transactionHashes", "quotedFeeRaw" ] }, { "type": "null" } ], "description": "For a step that paid an address the user approved: where the payout landed and its transaction ids, as a withdrawal's receipt shows them. `null` for a swap, a payout to the user's main wallet, a step that has not settled, or an older trade." }, "intentHashes": { "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The NEAR Intents ids of the intents that carried out this step, as 1Click reported them when it settled. Quote one to support to trace the step. They are on the confidential NEAR Intents ledger, which no public explorer shows. Empty until the step settles, and for a step that was refunded or did not run." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." } }, "required": [ "id", "index", "state", "inputToken", "outputToken", "debitRaw", "quoteOutputRaw", "settledOutputRaw", "minimumOutputRaw", "maximumInputRaw", "inputPriceUsd", "outputPriceUsd", "pricesObservedAt", "inputValueUsdAtPlan", "outputValueUsdAtPlan", "quoteInputUsd", "quoteOutputUsd", "createdAt", "signedAt", "settledAt", "receipt", "transferPayout", "intentHashes", "refundReason" ] }, "description": "The steps that actually ran, in plan order, each with its amounts and receipt. A planned step that never started has no entry." } }, "required": [ "id", "source", "request", "approval", "status", "failureReason", "outcome", "createdAt", "startedAt", "reportedAt", "plan", "legs" ], "description": "A trade the agent made or proposed from the agent wallet: what it asked for, who approved it, its `status`, and the plan it ran and the result of each step as evidence." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Prepare an order 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`. `POST /v1/users/{userId}/wallet/orders/prepare` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequestInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/orders/prepare' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The order's terms, the message to sign and the request key. ```json { "description": "The order's terms, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedOrder" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `asset_not_tradable` — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off - `limit_orders_disabled` — limit orders are not enabled for this user - `agent_api_orders_unavailable` — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_tradable` — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `limit_orders_disabled` — limit orders are not enabled for this user\n- `agent_api_orders_unavailable` — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `order_changed` — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again ```json { "description": "The operation lost to the current state.\n\n- `order_changed` — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.prepareOrder", "summary": "Prepare an order", "tags": [ "wallets" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequestInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The order's terms, the message to sign and the request key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreparedOrder" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_tradable` — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `limit_orders_disabled` — limit orders are not enabled for this user\n- `agent_api_orders_unavailable` — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `order_changed` — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "OrderRequestInput": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit. It leaves the agent wallet when the order is placed." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. What the order buys comes back to the agent wallet." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The least the order sells at, as bought-asset units per ONE sold unit, written as a plain decimal: \"5\" means at least 5 of the bought asset for each one sold. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order rests before it expires, in whole hours from 1 to 720 (30 days)." }, "context": { "type": "object", "properties": { "country": { "description": "The country the user is making this request from, as an uppercase ISO 3166-1 alpha-2 code such as `GB`, resolved by your server from the request (your edge's IP geolocation), never taken from the browser. A tokenized stock is traded only when this reports a country where it is available.", "type": "string", "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false, "description": "What your app knows about the user as they make this request. It applies to this request only, so send it with every request that may trade a tokenized stock." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "limitPrice", "expiresInHours" ], "additionalProperties": false, "description": "What to sell, how much, what to buy, the least it sells at and how long it rests; preparing fills in the least the whole order receives. An order of a tokenized stock also needs `context.country`." }, "PreparedOrder": { "type": "object", "properties": { "terms": { "description": "The exact terms to show the user and send, unchanged, to Place an order: the request plus the least the whole order receives at its limit price.", "$ref": "#/components/schemas/OrderTerms" }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "This order's id for retries: send it as the `Idempotency-Key` of Place an order, and filter List orders on it after a timeout." }, "authorization": { "description": "The message the user signs to allow exactly these terms. Call Place an order before `authorization.expiresAt`.", "$ref": "#/components/schemas/MessageToSign" } }, "required": [ "terms", "requestKey", "authorization" ], "description": "A limit order's exact terms, the message the user signs for them, and the key to place it with." }, "OrderTerms": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit. It leaves the agent wallet when the order is placed." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. What the order buys comes back to the agent wallet." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The least the order sells at, as bought-asset units per ONE sold unit, written as a plain decimal: \"5\" means at least 5 of the bought asset for each one sold. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order rests before it expires, in whole hours from 1 to 720 (30 days)." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the whole order receives at its limit price, in the bought asset's smallest unit, rounded up. This is the floor the user signs: an order that would receive less is never placed." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "limitPrice", "expiresInHours", "minimumReceivedRaw" ], "description": "The exact terms of a limit order in the agent wallet: what it sells, what it buys, the least it sells at, how long it rests, and the least it receives in all." }, "MessageToSign": { "type": "object", "properties": { "message": { "type": "string", "description": "The text the user signs with their registered wallet or passkey. Sign it exactly as returned: a changed character makes the signature invalid." }, "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The user's registered wallet or passkey, the only one whose signature is accepted. Send it back unchanged beside the signature." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the signature stops being accepted, about four and a half minutes after this was issued. Send it back unchanged beside the signature." }, "recipient": { "description": "NEAR wallets only: the `recipient` to pass to `signMessage` together with the message.", "type": "string" } }, "required": [ "message", "controllerId", "expiresAt" ], "description": "A message for the user to sign with their registered wallet or passkey, and the values to send back with the signature." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Place an order 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. `POST /v1/users/{userId}/wallet/orders` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The prepared order's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same order back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrderInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/orders' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' \ --header 'Content-Type: application/json' \ --data '{ "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "100000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "limitPrice": "0.357142857143", "minimumReceivedRaw": "35714285714300000000000000", "expiresInHours": 720 }, "authorization": { "controllerId": "ee79012b-d19c-44f8-aef8-828b88142809", "expiresAt": "2026-09-22T18:04:30.000Z", "signature": { "kind": "evm", "signature": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" } } }' ``` ## Responses ### 200 The order and its current state. ```json { "description": "The order and its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOrder" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `asset_not_tradable` — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off - `limit_orders_disabled` — limit orders are not enabled for this user - `agent_api_orders_unavailable` — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_tradable` — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `limit_orders_disabled` — limit orders are not enabled for this user\n- `agent_api_orders_unavailable` — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `order_changed` — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `order_changed` — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.placeOrder", "summary": "Place an order", "tags": [ "wallets" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrderInput" } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "The prepared order's `requestKey`, which the user's signature names. Send the same key and body again to retry safely: you get the same order back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The order and its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOrder" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `asset_not_tradable` — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `limit_orders_disabled` — limit orders are not enabled for this user\n- `agent_api_orders_unavailable` — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `order_changed` — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "PlaceOrderInput": { "type": "object", "properties": { "terms": { "description": "The prepared order's `terms`, unchanged.", "$ref": "#/components/schemas/OrderTermsInput" }, "authorization": { "type": "object", "properties": { "controllerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `controllerId` returned with the message, unchanged: the wallet that signed." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The `expiresAt` returned with the message, unchanged, character for character." }, "signature": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "evm", "description": "An EIP-191 personal-message signature by the current controller." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte hexadecimal signature over the exact supplied message." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webauthn", "description": "A user-verified WebAuthn assertion over the message digest." }, "credentialId": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The signing credential identifier encoded as base64url." }, "clientDataJSON": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's client-data JSON bytes encoded as base64url." }, "authenticatorData": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator data bytes encoded as base64url." }, "signature": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$", "description": "The authenticator's signature encoded as base64url." }, "userHandle": { "description": "The optional authenticator user handle encoded as base64url.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "kind", "credentialId", "clientDataJSON", "authenticatorData", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "near", "description": "A NEP-413 `signMessage` result over `{message, nonce, recipient}`, where `recipient` is the host of Fin's audience." }, "publicKey": { "type": "string", "pattern": "^ed25519:[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "The signing key as the wallet reports it (`ed25519:` then base58)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$", "description": "The 32-byte nonce the caller gave the wallet, in padded standard base64." } }, "required": [ "kind", "publicKey", "signature", "nonce" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana", "description": "A Solana `signMessage` Ed25519 signature over the exact UTF-8 message bytes." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stellar", "description": "A SEP-53 signature: Ed25519 over sha256(\"Stellar Signed Message:\\n\" + message)." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." } }, "required": [ "kind", "signature" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ton", "description": "A TON Connect `signData` result for a `text` payload that is exactly the message." }, "signature": { "type": "string", "pattern": "^[A-Za-z0-9+/]{86}==$", "description": "The 64-byte Ed25519 signature in padded standard base64." }, "address": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The signing wallet's address exactly as the wallet returned it." }, "domain": { "type": "string", "minLength": 1, "maxLength": 253, "description": "The dApp domain the wallet attested; it must be a partner-registered origin's host." }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The wallet's signing time in UNIX seconds; it must be within five minutes." } }, "required": [ "kind", "signature", "address", "domain", "timestamp" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tron", "description": "A TIP-191 `signMessageV2` signature over the exact message." }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$", "description": "The 65-byte recoverable secp256k1 signature in hexadecimal." } }, "required": [ "kind", "signature" ], "additionalProperties": false } ], "description": "The user's signature of the `message`, exactly as the API returned it." } }, "required": [ "controllerId", "expiresAt", "signature" ], "additionalProperties": false, "description": "The user's signature of the prepared order's `authorization.message`, with its `controllerId` and `expiresAt` unchanged. Checked on arrival and never stored." }, "context": { "description": "What your app knows about the user as they make this request. An order of a tokenized stock needs `context.country` again here: it applies to this request only, and a retry that finds its order needs none.", "type": "object", "properties": { "country": { "description": "The country the user is making this request from, as an uppercase ISO 3166-1 alpha-2 code such as `GB`, resolved by your server from the request (your edge's IP geolocation), never taken from the browser. A tokenized stock is traded only when this reports a country where it is available.", "type": "string", "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false } }, "required": [ "terms", "authorization" ], "additionalProperties": false, "examples": [ { "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "100000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "limitPrice": "0.357142857143", "minimumReceivedRaw": "35714285714300000000000000", "expiresInHours": 720 }, "authorization": { "controllerId": "ee79012b-d19c-44f8-aef8-828b88142809", "expiresAt": "2026-09-22T18:04:30.000Z", "signature": { "kind": "evm", "signature": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000" } } } ], "description": "A prepared limit order and the user's signature allowing it." }, "OrderTermsInput": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit. It leaves the agent wallet when the order is placed." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. What the order buys comes back to the agent wallet." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The least the order sells at, as bought-asset units per ONE sold unit, written as a plain decimal: \"5\" means at least 5 of the bought asset for each one sold. Never scale it by decimals." }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "How long the order rests before it expires, in whole hours from 1 to 720 (30 days)." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the whole order receives at its limit price, in the bought asset's smallest unit, rounded up. This is the floor the user signs: an order that would receive less is never placed." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "limitPrice", "expiresInHours", "minimumReceivedRaw" ], "additionalProperties": false, "description": "The exact terms of a limit order in the agent wallet: what it sells, what it buys, the least it sells at, how long it rests, and the least it receives in all." }, "WalletOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id; the provider's own id is `orderId`." }, "orderId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "The provider's order id, or `null` until the provider confirms the order. Treat it as opaque." }, "terms": { "type": "object", "properties": { "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The base asset the order sells, pinned to its token id and decimals." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The quote asset the order buys, pinned to its token id and decimals." }, "quantity": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base-asset amount to sell, in the base asset's smallest unit." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The minimum price a fill must reach: quote-asset units per one base unit, as a plain decimal." }, "deadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The absolute instant the resting order expires." } }, "required": [ "input", "output", "quantity", "limitPrice", "deadline" ], "description": "The approved terms the order was placed with; they never change." }, "state": { "type": "string", "enum": [ "prepared", "creating", "created", "signing", "funded", "unconfirmed", "abandoned" ], "description": "Where this order is in our own lifecycle: prepared/creating/created/signing/funded, plus unconfirmed (a lost response, never retried) and abandoned (refused before any signature)." }, "observation": { "anyOf": [ { "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The provider's opaque order id." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The base asset the order sells." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The quote asset the order buys." }, "quantity": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "The base-asset quantity the order rests on, in the base asset's smallest unit." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The resting limit price: quote-asset units per one base unit." }, "deadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The absolute instant the order expires at the provider." }, "fillStatus": { "type": "string", "enum": [ "AWAITING_DEPOSIT", "PENDING_CANCEL", "UNTRIGGERED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "EXPIRED" ], "description": "How much matched. Independent of whether any payout arrived." }, "payoutStatus": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "FAILED" ], "description": "Whether the output side is paying out; `COMPLETED` or `FAILED` is final, in progress is not." }, "isPayoutStatusFinal": { "type": "boolean", "description": "Whether the payout axis stopped moving. True covers a failed payout and is not a success flag." }, "depositedAmount": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "Cumulative funded input in the base asset's smallest unit; zero until funded." }, "filledInputRaw": { "anyOf": [ { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ], "description": "Successful fills' input total in atomic units, or null when an amount could not be read exactly." }, "filledOutputRaw": { "anyOf": [ { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ], "description": "Successful fills' output total in atomic units, or null when unknown; a full fill with no reported fills stays null." }, "cancelable": { "type": "boolean", "description": "Whether the provider may still accept a cancellation right now." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When this provider projection was last read." } }, "required": [ "orderId", "input", "output", "quantity", "limitPrice", "deadline", "fillStatus", "payoutStatus", "isPayoutStatusFinal", "depositedAmount", "filledInputRaw", "filledOutputRaw", "cancelable", "observedAt" ] }, { "type": "null" } ], "description": "What the provider last reported about fills and payouts, or `null` until it has been read." }, "position": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Time Fin observed this provider report; not a cash settlement time." }, "basis": { "type": "string", "const": "provider_report", "description": "Allocation reported by the bound order provider, not a wallet cash receipt." }, "restingInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Input atomic units still resting in the order; null when unknown, zero after matching ends." }, "filledInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Cumulative input atomic units in known successful fills; null when incomplete or conflicting." }, "filledOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Cumulative output atomic units from successful fills; does not establish a wallet receipt or current holding." }, "refund": { "anyOf": [ { "type": "object", "properties": { "principalRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Unfilled input principal allocated to refund clearing before unknown settlement fees; not spendable cash." }, "providerStatus": { "anyOf": [ { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "FAILED" ] }, { "type": "null" } ], "description": "Refund leg status, or null when no leg was reported; completion does not prove the net amount received." }, "txHash": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ], "description": "Provider-reported completed refund reference; not proof of an amount received." } }, "required": [ "principalRaw", "providerStatus", "txHash" ] }, { "type": "null" } ], "description": "Refund clearing claim for a terminal order, or null when none is reported." }, "withdrawals": { "maxItems": 1001, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "IN_PROGRESS", "description": "The provider reports this payout is in progress." } }, "required": [ "status" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "COMPLETED", "description": "The provider reports completion; this does not establish the exact net amount received." }, "txHash": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The provider's payout transaction reference, not an amount or a receipt reconciliation." } }, "required": [ "status", "txHash" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "FAILED", "description": "The provider reports this payout failed; the funds' disposition remains unresolved." }, "reason": { "description": "The provider's reason for the payout failure, when supplied.", "type": "string", "maxLength": 256 } }, "required": [ "status" ], "additionalProperties": {} } ] }, "description": "Provider payout references, deduplicated for display; no inferred cash credits." }, "reconciliation": { "type": "string", "enum": [ "not_required", "unreconciled" ], "description": "Not required only for proven never-funded empty orders; otherwise actual cash settlement remains unreconciled." } }, "required": [ "observedAt", "basis", "restingInputRaw", "filledInputRaw", "filledOutputRaw", "refund", "withdrawals", "reconciliation" ] }, { "type": "null" } ], "description": "Provider-reported order allocation and payout references, or null before a usable observation. Refund principal is before deductions and is not received wallet cash. Provider completion does not reconcile a payout." }, "fills": { "anyOf": [ { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1Click's id for this fill. Treat it as opaque." }, "inputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What this fill sold, in the sold asset's smallest unit, as 1Click reported it." }, "outputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What this fill bought, in the bought asset's smallest unit, as 1Click reported it: not proof of what reached the wallet." }, "filledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When 1Click says the fill happened; `null` when it gave no time Fin can read." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw this fill in 1Click's report; `null` for a fill Fin saw before it kept this." } }, "required": [ "id", "inputRaw", "outputRaw", "filledAt", "reportedAt" ] } }, { "type": "null" } ], "description": "Each fill 1Click reported for this order, oldest first: what it sold and bought, when it happened and when Fin first saw it. A fill's price is `outputRaw` per `inputRaw`, each at its asset's decimals. Empty before anything fills; `null` whenever `position.filledInputRaw` is (no usable report yet, or one whose fills cannot be read exactly)." }, "depositReportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw 1Click report that the order's funds arrived; `null` until then, and for an order whose funds arrived before Fin kept this." }, "paidOutAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw 1Click report the order ended (filled, cancelled or expired) with its payouts complete and final: what filled came back as the bought asset, and what did not fill came back as the sold one. `null` until then." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the order sells (`terms.quantity`) was worth when it was placed, at the last market price Fin kept at or before then (the prices portfolio history uses): a five-minute close from the ten minutes before the placement, else an hourly close from the two hours before it. `null` when Fin kept neither." }, "cancelRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user asked to cancel, or `null`. Asking is not proof the provider canceled or refunded." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "provider_refused", "verification_failed", "credentials_unavailable", "provider_unavailable", "placement_disabled", "account_busy", "expired" ] }, { "type": "null" } ], "description": "When `state` is `abandoned`, why nothing was funded; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount. `provider_refused`: the provider refused the order. `verification_failed`: the order or its funding transfer failed its checks, or would receive less than the minimum the user signed. `credentials_unavailable`: the wallet could not sign or reach the provider. `provider_unavailable`: NEAR Intents did not answer before the order was created, so nothing was placed; placing it again later may work. `placement_disabled`: this deployment does not sign trades. `account_busy`: another funding held the wallet. `expired`: the user's signed request ran out before the order started. Prepare and place a new order to try again." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation in which the agent placed the order; `null` for an order the user placed with Place an order." }, "approvalId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, { "type": "null" } ], "description": "The approval the user gave for the order in that conversation: open the conversation at its card to show where the order was asked for. `null` for an order the user placed with Place an order." }, "grid": { "anyOf": [ { "type": "object", "properties": { "gridId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grid's `id`: read it with Get a grid." }, "cell": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The grid cell the order was placed for, lowest first." } }, "required": [ "gridId", "cell" ] }, { "type": "null" } ], "description": "The grid that placed this order and the cell it rests for, or `null` for an order placed on its own." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the order was placed." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the order last changed." } }, "required": [ "id", "orderId", "terms", "state", "observation", "position", "fills", "depositReportedAt", "paidOutAt", "value", "cancelRequestedAt", "failureReason", "conversationId", "approvalId", "grid", "createdAt", "updatedAt" ], "description": "A limit order from the agent wallet: the approved terms, whether it is funded, how much has filled, and any cancellation." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List limit orders 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 /v1/users/{userId}/wallet/orders` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "requestKey", "required": false, "description": "Only the order placed with this `Idempotency-Key`: how to find it after Place an order timed out." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/orders' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of limit orders. ```json { "description": "A page of limit orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WalletOrder" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.listOrders", "summary": "List limit orders", "tags": [ "wallets" ], "description": "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`.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "requestKey", "required": false, "description": "Only the order placed with this `Idempotency-Key`: how to find it after Place an order timed out." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of limit orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WalletOrder" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "WalletOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id; the provider's own id is `orderId`." }, "orderId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "The provider's order id, or `null` until the provider confirms the order. Treat it as opaque." }, "terms": { "type": "object", "properties": { "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The base asset the order sells, pinned to its token id and decimals." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The quote asset the order buys, pinned to its token id and decimals." }, "quantity": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base-asset amount to sell, in the base asset's smallest unit." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The minimum price a fill must reach: quote-asset units per one base unit, as a plain decimal." }, "deadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The absolute instant the resting order expires." } }, "required": [ "input", "output", "quantity", "limitPrice", "deadline" ], "description": "The approved terms the order was placed with; they never change." }, "state": { "type": "string", "enum": [ "prepared", "creating", "created", "signing", "funded", "unconfirmed", "abandoned" ], "description": "Where this order is in our own lifecycle: prepared/creating/created/signing/funded, plus unconfirmed (a lost response, never retried) and abandoned (refused before any signature)." }, "observation": { "anyOf": [ { "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The provider's opaque order id." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The base asset the order sells." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The quote asset the order buys." }, "quantity": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "The base-asset quantity the order rests on, in the base asset's smallest unit." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The resting limit price: quote-asset units per one base unit." }, "deadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The absolute instant the order expires at the provider." }, "fillStatus": { "type": "string", "enum": [ "AWAITING_DEPOSIT", "PENDING_CANCEL", "UNTRIGGERED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "EXPIRED" ], "description": "How much matched. Independent of whether any payout arrived." }, "payoutStatus": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "FAILED" ], "description": "Whether the output side is paying out; `COMPLETED` or `FAILED` is final, in progress is not." }, "isPayoutStatusFinal": { "type": "boolean", "description": "Whether the payout axis stopped moving. True covers a failed payout and is not a success flag." }, "depositedAmount": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "Cumulative funded input in the base asset's smallest unit; zero until funded." }, "filledInputRaw": { "anyOf": [ { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ], "description": "Successful fills' input total in atomic units, or null when an amount could not be read exactly." }, "filledOutputRaw": { "anyOf": [ { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ], "description": "Successful fills' output total in atomic units, or null when unknown; a full fill with no reported fills stays null." }, "cancelable": { "type": "boolean", "description": "Whether the provider may still accept a cancellation right now." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When this provider projection was last read." } }, "required": [ "orderId", "input", "output", "quantity", "limitPrice", "deadline", "fillStatus", "payoutStatus", "isPayoutStatusFinal", "depositedAmount", "filledInputRaw", "filledOutputRaw", "cancelable", "observedAt" ] }, { "type": "null" } ], "description": "What the provider last reported about fills and payouts, or `null` until it has been read." }, "position": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Time Fin observed this provider report; not a cash settlement time." }, "basis": { "type": "string", "const": "provider_report", "description": "Allocation reported by the bound order provider, not a wallet cash receipt." }, "restingInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Input atomic units still resting in the order; null when unknown, zero after matching ends." }, "filledInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Cumulative input atomic units in known successful fills; null when incomplete or conflicting." }, "filledOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Cumulative output atomic units from successful fills; does not establish a wallet receipt or current holding." }, "refund": { "anyOf": [ { "type": "object", "properties": { "principalRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Unfilled input principal allocated to refund clearing before unknown settlement fees; not spendable cash." }, "providerStatus": { "anyOf": [ { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "FAILED" ] }, { "type": "null" } ], "description": "Refund leg status, or null when no leg was reported; completion does not prove the net amount received." }, "txHash": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ], "description": "Provider-reported completed refund reference; not proof of an amount received." } }, "required": [ "principalRaw", "providerStatus", "txHash" ] }, { "type": "null" } ], "description": "Refund clearing claim for a terminal order, or null when none is reported." }, "withdrawals": { "maxItems": 1001, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "IN_PROGRESS", "description": "The provider reports this payout is in progress." } }, "required": [ "status" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "COMPLETED", "description": "The provider reports completion; this does not establish the exact net amount received." }, "txHash": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The provider's payout transaction reference, not an amount or a receipt reconciliation." } }, "required": [ "status", "txHash" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "FAILED", "description": "The provider reports this payout failed; the funds' disposition remains unresolved." }, "reason": { "description": "The provider's reason for the payout failure, when supplied.", "type": "string", "maxLength": 256 } }, "required": [ "status" ], "additionalProperties": {} } ] }, "description": "Provider payout references, deduplicated for display; no inferred cash credits." }, "reconciliation": { "type": "string", "enum": [ "not_required", "unreconciled" ], "description": "Not required only for proven never-funded empty orders; otherwise actual cash settlement remains unreconciled." } }, "required": [ "observedAt", "basis", "restingInputRaw", "filledInputRaw", "filledOutputRaw", "refund", "withdrawals", "reconciliation" ] }, { "type": "null" } ], "description": "Provider-reported order allocation and payout references, or null before a usable observation. Refund principal is before deductions and is not received wallet cash. Provider completion does not reconcile a payout." }, "fills": { "anyOf": [ { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1Click's id for this fill. Treat it as opaque." }, "inputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What this fill sold, in the sold asset's smallest unit, as 1Click reported it." }, "outputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What this fill bought, in the bought asset's smallest unit, as 1Click reported it: not proof of what reached the wallet." }, "filledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When 1Click says the fill happened; `null` when it gave no time Fin can read." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw this fill in 1Click's report; `null` for a fill Fin saw before it kept this." } }, "required": [ "id", "inputRaw", "outputRaw", "filledAt", "reportedAt" ] } }, { "type": "null" } ], "description": "Each fill 1Click reported for this order, oldest first: what it sold and bought, when it happened and when Fin first saw it. A fill's price is `outputRaw` per `inputRaw`, each at its asset's decimals. Empty before anything fills; `null` whenever `position.filledInputRaw` is (no usable report yet, or one whose fills cannot be read exactly)." }, "depositReportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw 1Click report that the order's funds arrived; `null` until then, and for an order whose funds arrived before Fin kept this." }, "paidOutAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw 1Click report the order ended (filled, cancelled or expired) with its payouts complete and final: what filled came back as the bought asset, and what did not fill came back as the sold one. `null` until then." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the order sells (`terms.quantity`) was worth when it was placed, at the last market price Fin kept at or before then (the prices portfolio history uses): a five-minute close from the ten minutes before the placement, else an hourly close from the two hours before it. `null` when Fin kept neither." }, "cancelRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user asked to cancel, or `null`. Asking is not proof the provider canceled or refunded." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "provider_refused", "verification_failed", "credentials_unavailable", "provider_unavailable", "placement_disabled", "account_busy", "expired" ] }, { "type": "null" } ], "description": "When `state` is `abandoned`, why nothing was funded; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount. `provider_refused`: the provider refused the order. `verification_failed`: the order or its funding transfer failed its checks, or would receive less than the minimum the user signed. `credentials_unavailable`: the wallet could not sign or reach the provider. `provider_unavailable`: NEAR Intents did not answer before the order was created, so nothing was placed; placing it again later may work. `placement_disabled`: this deployment does not sign trades. `account_busy`: another funding held the wallet. `expired`: the user's signed request ran out before the order started. Prepare and place a new order to try again." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation in which the agent placed the order; `null` for an order the user placed with Place an order." }, "approvalId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, { "type": "null" } ], "description": "The approval the user gave for the order in that conversation: open the conversation at its card to show where the order was asked for. `null` for an order the user placed with Place an order." }, "grid": { "anyOf": [ { "type": "object", "properties": { "gridId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grid's `id`: read it with Get a grid." }, "cell": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The grid cell the order was placed for, lowest first." } }, "required": [ "gridId", "cell" ] }, { "type": "null" } ], "description": "The grid that placed this order and the cell it rests for, or `null` for an order placed on its own." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the order was placed." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the order last changed." } }, "required": [ "id", "orderId", "terms", "state", "observation", "position", "fills", "depositReportedAt", "paidOutAt", "value", "cancelRequestedAt", "failureReason", "conversationId", "approvalId", "grid", "createdAt", "updatedAt" ], "description": "A limit order from the agent wallet: the approved terms, whether it is funded, how much has filled, and any cancellation." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a limit order Returns a limit order and its current state. `unconfirmed` means the provider's answer was lost; never place a replacement, keep checking. `GET /v1/users/{userId}/wallet/orders/{orderId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "orderId", "required": true, "description": "The order's `id` (not the provider's `orderId`)." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/orders/YOUR_ORDER_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The limit order. ```json { "description": "The limit order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOrder" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getOrder", "summary": "Get a limit order", "tags": [ "wallets" ], "description": "Returns a limit order and its current state. `unconfirmed` means the provider's answer was lost; never place a replacement, keep checking.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "orderId", "required": true, "description": "The order's `id` (not the provider's `orderId`)." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The limit order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOrder" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "WalletOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id; the provider's own id is `orderId`." }, "orderId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "The provider's order id, or `null` until the provider confirms the order. Treat it as opaque." }, "terms": { "type": "object", "properties": { "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The base asset the order sells, pinned to its token id and decimals." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The quote asset the order buys, pinned to its token id and decimals." }, "quantity": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base-asset amount to sell, in the base asset's smallest unit." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The minimum price a fill must reach: quote-asset units per one base unit, as a plain decimal." }, "deadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The absolute instant the resting order expires." } }, "required": [ "input", "output", "quantity", "limitPrice", "deadline" ], "description": "The approved terms the order was placed with; they never change." }, "state": { "type": "string", "enum": [ "prepared", "creating", "created", "signing", "funded", "unconfirmed", "abandoned" ], "description": "Where this order is in our own lifecycle: prepared/creating/created/signing/funded, plus unconfirmed (a lost response, never retried) and abandoned (refused before any signature)." }, "observation": { "anyOf": [ { "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The provider's opaque order id." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The base asset the order sells." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The quote asset the order buys." }, "quantity": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "The base-asset quantity the order rests on, in the base asset's smallest unit." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The resting limit price: quote-asset units per one base unit." }, "deadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The absolute instant the order expires at the provider." }, "fillStatus": { "type": "string", "enum": [ "AWAITING_DEPOSIT", "PENDING_CANCEL", "UNTRIGGERED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "EXPIRED" ], "description": "How much matched. Independent of whether any payout arrived." }, "payoutStatus": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "FAILED" ], "description": "Whether the output side is paying out; `COMPLETED` or `FAILED` is final, in progress is not." }, "isPayoutStatusFinal": { "type": "boolean", "description": "Whether the payout axis stopped moving. True covers a failed payout and is not a success flag." }, "depositedAmount": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "Cumulative funded input in the base asset's smallest unit; zero until funded." }, "filledInputRaw": { "anyOf": [ { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ], "description": "Successful fills' input total in atomic units, or null when an amount could not be read exactly." }, "filledOutputRaw": { "anyOf": [ { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ], "description": "Successful fills' output total in atomic units, or null when unknown; a full fill with no reported fills stays null." }, "cancelable": { "type": "boolean", "description": "Whether the provider may still accept a cancellation right now." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When this provider projection was last read." } }, "required": [ "orderId", "input", "output", "quantity", "limitPrice", "deadline", "fillStatus", "payoutStatus", "isPayoutStatusFinal", "depositedAmount", "filledInputRaw", "filledOutputRaw", "cancelable", "observedAt" ] }, { "type": "null" } ], "description": "What the provider last reported about fills and payouts, or `null` until it has been read." }, "position": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Time Fin observed this provider report; not a cash settlement time." }, "basis": { "type": "string", "const": "provider_report", "description": "Allocation reported by the bound order provider, not a wallet cash receipt." }, "restingInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Input atomic units still resting in the order; null when unknown, zero after matching ends." }, "filledInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Cumulative input atomic units in known successful fills; null when incomplete or conflicting." }, "filledOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Cumulative output atomic units from successful fills; does not establish a wallet receipt or current holding." }, "refund": { "anyOf": [ { "type": "object", "properties": { "principalRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Unfilled input principal allocated to refund clearing before unknown settlement fees; not spendable cash." }, "providerStatus": { "anyOf": [ { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "FAILED" ] }, { "type": "null" } ], "description": "Refund leg status, or null when no leg was reported; completion does not prove the net amount received." }, "txHash": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ], "description": "Provider-reported completed refund reference; not proof of an amount received." } }, "required": [ "principalRaw", "providerStatus", "txHash" ] }, { "type": "null" } ], "description": "Refund clearing claim for a terminal order, or null when none is reported." }, "withdrawals": { "maxItems": 1001, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "IN_PROGRESS", "description": "The provider reports this payout is in progress." } }, "required": [ "status" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "COMPLETED", "description": "The provider reports completion; this does not establish the exact net amount received." }, "txHash": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The provider's payout transaction reference, not an amount or a receipt reconciliation." } }, "required": [ "status", "txHash" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "FAILED", "description": "The provider reports this payout failed; the funds' disposition remains unresolved." }, "reason": { "description": "The provider's reason for the payout failure, when supplied.", "type": "string", "maxLength": 256 } }, "required": [ "status" ], "additionalProperties": {} } ] }, "description": "Provider payout references, deduplicated for display; no inferred cash credits." }, "reconciliation": { "type": "string", "enum": [ "not_required", "unreconciled" ], "description": "Not required only for proven never-funded empty orders; otherwise actual cash settlement remains unreconciled." } }, "required": [ "observedAt", "basis", "restingInputRaw", "filledInputRaw", "filledOutputRaw", "refund", "withdrawals", "reconciliation" ] }, { "type": "null" } ], "description": "Provider-reported order allocation and payout references, or null before a usable observation. Refund principal is before deductions and is not received wallet cash. Provider completion does not reconcile a payout." }, "fills": { "anyOf": [ { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1Click's id for this fill. Treat it as opaque." }, "inputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What this fill sold, in the sold asset's smallest unit, as 1Click reported it." }, "outputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What this fill bought, in the bought asset's smallest unit, as 1Click reported it: not proof of what reached the wallet." }, "filledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When 1Click says the fill happened; `null` when it gave no time Fin can read." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw this fill in 1Click's report; `null` for a fill Fin saw before it kept this." } }, "required": [ "id", "inputRaw", "outputRaw", "filledAt", "reportedAt" ] } }, { "type": "null" } ], "description": "Each fill 1Click reported for this order, oldest first: what it sold and bought, when it happened and when Fin first saw it. A fill's price is `outputRaw` per `inputRaw`, each at its asset's decimals. Empty before anything fills; `null` whenever `position.filledInputRaw` is (no usable report yet, or one whose fills cannot be read exactly)." }, "depositReportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw 1Click report that the order's funds arrived; `null` until then, and for an order whose funds arrived before Fin kept this." }, "paidOutAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw 1Click report the order ended (filled, cancelled or expired) with its payouts complete and final: what filled came back as the bought asset, and what did not fill came back as the sold one. `null` until then." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the order sells (`terms.quantity`) was worth when it was placed, at the last market price Fin kept at or before then (the prices portfolio history uses): a five-minute close from the ten minutes before the placement, else an hourly close from the two hours before it. `null` when Fin kept neither." }, "cancelRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user asked to cancel, or `null`. Asking is not proof the provider canceled or refunded." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "provider_refused", "verification_failed", "credentials_unavailable", "provider_unavailable", "placement_disabled", "account_busy", "expired" ] }, { "type": "null" } ], "description": "When `state` is `abandoned`, why nothing was funded; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount. `provider_refused`: the provider refused the order. `verification_failed`: the order or its funding transfer failed its checks, or would receive less than the minimum the user signed. `credentials_unavailable`: the wallet could not sign or reach the provider. `provider_unavailable`: NEAR Intents did not answer before the order was created, so nothing was placed; placing it again later may work. `placement_disabled`: this deployment does not sign trades. `account_busy`: another funding held the wallet. `expired`: the user's signed request ran out before the order started. Prepare and place a new order to try again." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation in which the agent placed the order; `null` for an order the user placed with Place an order." }, "approvalId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, { "type": "null" } ], "description": "The approval the user gave for the order in that conversation: open the conversation at its card to show where the order was asked for. `null` for an order the user placed with Place an order." }, "grid": { "anyOf": [ { "type": "object", "properties": { "gridId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grid's `id`: read it with Get a grid." }, "cell": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The grid cell the order was placed for, lowest first." } }, "required": [ "gridId", "cell" ] }, { "type": "null" } ], "description": "The grid that placed this order and the cell it rests for, or `null` for an order placed on its own." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the order was placed." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the order last changed." } }, "required": [ "id", "orderId", "terms", "state", "observation", "position", "fills", "depositReportedAt", "paidOutAt", "value", "cancelRequestedAt", "failureReason", "conversationId", "approvalId", "grid", "createdAt", "updatedAt" ], "description": "A limit order from the agent wallet: the approved terms, whether it is funded, how much has filled, and any cancellation." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Cancel a limit order 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. `POST /v1/users/{userId}/wallet/orders/{orderId}/cancel` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "orderId", "required": true, "description": "The order's `id` (not the provider's `orderId`)." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/orders/YOUR_ORDER_ID/cancel' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The order, with the cancellation requested. ```json { "description": "The order, with the cancellation requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOrder" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `order_not_cancelable` — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands ```json { "description": "The operation lost to the current state.\n\n- `order_not_cancelable` — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it - `provider_unavailable` — an external provider the call depends on did not answer ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.cancelOrder", "summary": "Cancel a limit order", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "orderId", "required": true, "description": "The order's `id` (not the provider's `orderId`)." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The order, with the cancellation requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOrder" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `order_not_cancelable` — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it\n- `provider_unavailable` — an external provider the call depends on did not answer", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "components": { "schemas": { "WalletOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id; the provider's own id is `orderId`." }, "orderId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "The provider's order id, or `null` until the provider confirms the order. Treat it as opaque." }, "terms": { "type": "object", "properties": { "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The base asset the order sells, pinned to its token id and decimals." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The quote asset the order buys, pinned to its token id and decimals." }, "quantity": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base-asset amount to sell, in the base asset's smallest unit." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The minimum price a fill must reach: quote-asset units per one base unit, as a plain decimal." }, "deadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The absolute instant the resting order expires." } }, "required": [ "input", "output", "quantity", "limitPrice", "deadline" ], "description": "The approved terms the order was placed with; they never change." }, "state": { "type": "string", "enum": [ "prepared", "creating", "created", "signing", "funded", "unconfirmed", "abandoned" ], "description": "Where this order is in our own lifecycle: prepared/creating/created/signing/funded, plus unconfirmed (a lost response, never retried) and abandoned (refused before any signature)." }, "observation": { "anyOf": [ { "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The provider's opaque order id." }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The base asset the order sells." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The quote asset the order buys." }, "quantity": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "The base-asset quantity the order rests on, in the base asset's smallest unit." }, "limitPrice": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The resting limit price: quote-asset units per one base unit." }, "deadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The absolute instant the order expires at the provider." }, "fillStatus": { "type": "string", "enum": [ "AWAITING_DEPOSIT", "PENDING_CANCEL", "UNTRIGGERED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "EXPIRED" ], "description": "How much matched. Independent of whether any payout arrived." }, "payoutStatus": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "FAILED" ], "description": "Whether the output side is paying out; `COMPLETED` or `FAILED` is final, in progress is not." }, "isPayoutStatusFinal": { "type": "boolean", "description": "Whether the payout axis stopped moving. True covers a failed payout and is not a success flag." }, "depositedAmount": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "Cumulative funded input in the base asset's smallest unit; zero until funded." }, "filledInputRaw": { "anyOf": [ { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ], "description": "Successful fills' input total in atomic units, or null when an amount could not be read exactly." }, "filledOutputRaw": { "anyOf": [ { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$" }, { "type": "null" } ], "description": "Successful fills' output total in atomic units, or null when unknown; a full fill with no reported fills stays null." }, "cancelable": { "type": "boolean", "description": "Whether the provider may still accept a cancellation right now." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When this provider projection was last read." } }, "required": [ "orderId", "input", "output", "quantity", "limitPrice", "deadline", "fillStatus", "payoutStatus", "isPayoutStatusFinal", "depositedAmount", "filledInputRaw", "filledOutputRaw", "cancelable", "observedAt" ] }, { "type": "null" } ], "description": "What the provider last reported about fills and payouts, or `null` until it has been read." }, "position": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Time Fin observed this provider report; not a cash settlement time." }, "basis": { "type": "string", "const": "provider_report", "description": "Allocation reported by the bound order provider, not a wallet cash receipt." }, "restingInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Input atomic units still resting in the order; null when unknown, zero after matching ends." }, "filledInputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Cumulative input atomic units in known successful fills; null when incomplete or conflicting." }, "filledOutputRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Cumulative output atomic units from successful fills; does not establish a wallet receipt or current holding." }, "refund": { "anyOf": [ { "type": "object", "properties": { "principalRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Unfilled input principal allocated to refund clearing before unknown settlement fees; not spendable cash." }, "providerStatus": { "anyOf": [ { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "FAILED" ] }, { "type": "null" } ], "description": "Refund leg status, or null when no leg was reported; completion does not prove the net amount received." }, "txHash": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ], "description": "Provider-reported completed refund reference; not proof of an amount received." } }, "required": [ "principalRaw", "providerStatus", "txHash" ] }, { "type": "null" } ], "description": "Refund clearing claim for a terminal order, or null when none is reported." }, "withdrawals": { "maxItems": 1001, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "IN_PROGRESS", "description": "The provider reports this payout is in progress." } }, "required": [ "status" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "COMPLETED", "description": "The provider reports completion; this does not establish the exact net amount received." }, "txHash": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The provider's payout transaction reference, not an amount or a receipt reconciliation." } }, "required": [ "status", "txHash" ], "additionalProperties": {} }, { "type": "object", "properties": { "status": { "type": "string", "const": "FAILED", "description": "The provider reports this payout failed; the funds' disposition remains unresolved." }, "reason": { "description": "The provider's reason for the payout failure, when supplied.", "type": "string", "maxLength": 256 } }, "required": [ "status" ], "additionalProperties": {} } ] }, "description": "Provider payout references, deduplicated for display; no inferred cash credits." }, "reconciliation": { "type": "string", "enum": [ "not_required", "unreconciled" ], "description": "Not required only for proven never-funded empty orders; otherwise actual cash settlement remains unreconciled." } }, "required": [ "observedAt", "basis", "restingInputRaw", "filledInputRaw", "filledOutputRaw", "refund", "withdrawals", "reconciliation" ] }, { "type": "null" } ], "description": "Provider-reported order allocation and payout references, or null before a usable observation. Refund principal is before deductions and is not received wallet cash. Provider completion does not reconcile a payout." }, "fills": { "anyOf": [ { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "1Click's id for this fill. Treat it as opaque." }, "inputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What this fill sold, in the sold asset's smallest unit, as 1Click reported it." }, "outputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What this fill bought, in the bought asset's smallest unit, as 1Click reported it: not proof of what reached the wallet." }, "filledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When 1Click says the fill happened; `null` when it gave no time Fin can read." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw this fill in 1Click's report; `null` for a fill Fin saw before it kept this." } }, "required": [ "id", "inputRaw", "outputRaw", "filledAt", "reportedAt" ] } }, { "type": "null" } ], "description": "Each fill 1Click reported for this order, oldest first: what it sold and bought, when it happened and when Fin first saw it. A fill's price is `outputRaw` per `inputRaw`, each at its asset's decimals. Empty before anything fills; `null` whenever `position.filledInputRaw` is (no usable report yet, or one whose fills cannot be read exactly)." }, "depositReportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw 1Click report that the order's funds arrived; `null` until then, and for an order whose funds arrived before Fin kept this." }, "paidOutAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw 1Click report the order ended (filled, cancelled or expired) with its payouts complete and final: what filled came back as the bought asset, and what did not fill came back as the sold one. `null` until then." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the order sells (`terms.quantity`) was worth when it was placed, at the last market price Fin kept at or before then (the prices portfolio history uses): a five-minute close from the ten minutes before the placement, else an hourly close from the two hours before it. `null` when Fin kept neither." }, "cancelRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user asked to cancel, or `null`. Asking is not proof the provider canceled or refunded." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "provider_refused", "verification_failed", "credentials_unavailable", "provider_unavailable", "placement_disabled", "account_busy", "expired" ] }, { "type": "null" } ], "description": "When `state` is `abandoned`, why nothing was funded; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount. `provider_refused`: the provider refused the order. `verification_failed`: the order or its funding transfer failed its checks, or would receive less than the minimum the user signed. `credentials_unavailable`: the wallet could not sign or reach the provider. `provider_unavailable`: NEAR Intents did not answer before the order was created, so nothing was placed; placing it again later may work. `placement_disabled`: this deployment does not sign trades. `account_busy`: another funding held the wallet. `expired`: the user's signed request ran out before the order started. Prepare and place a new order to try again." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation in which the agent placed the order; `null` for an order the user placed with Place an order." }, "approvalId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, { "type": "null" } ], "description": "The approval the user gave for the order in that conversation: open the conversation at its card to show where the order was asked for. `null` for an order the user placed with Place an order." }, "grid": { "anyOf": [ { "type": "object", "properties": { "gridId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grid's `id`: read it with Get a grid." }, "cell": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The grid cell the order was placed for, lowest first." } }, "required": [ "gridId", "cell" ] }, { "type": "null" } ], "description": "The grid that placed this order and the cell it rests for, or `null` for an order placed on its own." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the order was placed." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the order last changed." } }, "required": [ "id", "orderId", "terms", "state", "observation", "position", "fills", "depositReportedAt", "paidOutAt", "value", "cancelRequestedAt", "failureReason", "conversationId", "approvalId", "grid", "createdAt", "updatedAt" ], "description": "A limit order from the agent wallet: the approved terms, whether it is funded, how much has filled, and any cancellation." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List grids 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 /v1/users/{userId}/wallet/grids` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/grids' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of grids. ```json { "description": "A page of grids.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Grid" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.listGrids", "summary": "List grids", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of grids.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Grid" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Grid": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grid's id." }, "state": { "type": "string", "enum": [ "active", "paused", "stopping", "stopped", "expired", "failed" ], "description": "`active`: cells place and re-arm. `paused`: no order rests and none is placed. `stopping`: its orders are being cancelled. `stopped`, `expired` and `failed` are final." }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "cancelled", "expired", "grant_revoked" ] }, { "type": "null" } ], "description": "Why the grid is stopping or ended: `cancelled` by the user, `expired` at `validUntil`, or `grant_revoked`. `null` while it runs or is paused." }, "terms": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "The exact terms the user approved; they never change." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends and its last orders expire." }, "cells": { "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The cell's position, lowest first." }, "low": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell buys at." }, "high": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell sells at." }, "side": { "type": "string", "enum": [ "buy", "sell", "idle" ], "description": "The side the cell's next or current order is on, or `idle` for none." }, "state": { "type": "string", "enum": [ "idle", "pending", "placing", "resting", "stalled" ], "description": "`pending`: waits to place. `placing`: an order is being created and funded. `resting`: its order is at the provider. `idle`: places nothing. `stalled`: stopped re-placing after orders ended unfilled too often, or an ending it could not read; the rest of the grid keeps running." }, "order": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's `id`: read it with Get an order for its terms, fills and payouts." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "`buy`: the cell buys its quantity at its low level. `sell`: it sells it at its high level." }, "state": { "type": "string", "enum": [ "prepared", "creating", "created", "signing", "funded", "unconfirmed", "abandoned" ], "description": "Where the order is in our own lifecycle: prepared through funded, unconfirmed or abandoned." }, "fillStatus": { "anyOf": [ { "type": "string", "enum": [ "AWAITING_DEPOSIT", "PENDING_CANCEL", "UNTRIGGERED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "EXPIRED" ] }, { "type": "null" } ], "description": "What the provider last reported about matching, or `null` until it was read." } }, "required": [ "id", "side", "state", "fillStatus" ], "description": "The order the cell has resting or being placed now." }, { "type": "null" } ], "description": "The order the cell rests or is placing now, or `null` when it has none." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times the cell bought at its low level and then sold at its high level." }, "realizedQuoteRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What those cycles earned, in the quote asset's smallest unit: each sale's received amount less its buy's cost." } }, "required": [ "index", "low", "high", "side", "state", "order", "cycles", "realizedQuoteRaw" ], "description": "One cell of the grid: the span between two adjacent levels." }, "description": "Every cell of the grid, lowest first." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Completed buy-then-sell cycles across every cell." }, "realizedProfit": { "type": "object", "properties": { "raw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "In the quote asset's smallest unit." }, "decimal": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The same amount in whole units of the asset, as an exact plain decimal." } }, "required": [ "raw", "decimal" ], "description": "What the completed cycles earned, in the quote asset." }, "heldBaseRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The base the grid's filled buys hold for its sell cells, in the base asset's smallest unit. It stays in the agent wallet when the grid ends." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation in which the user approved the grid." }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that created the grid." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid or one of its cells last changed." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the grid ended, or `null`." } }, "required": [ "id", "state", "stopReason", "terms", "validUntil", "cells", "cycles", "realizedProfit", "heldBaseRaw", "conversationId", "approvalId", "createdAt", "updatedAt", "endedAt" ], "description": "A grid of resting limit orders across a price range: its approved terms, each cell's live order, completed cycles and realized profit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get a grid 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. `GET /v1/users/{userId}/wallet/grids/{gridId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "gridId", "required": true, "description": "The grid's `id`." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/grids/YOUR_GRID_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The grid. ```json { "description": "The grid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grid" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.getGrid", "summary": "Get a grid", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "gridId", "required": true, "description": "The grid's `id`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The grid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grid" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Grid": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grid's id." }, "state": { "type": "string", "enum": [ "active", "paused", "stopping", "stopped", "expired", "failed" ], "description": "`active`: cells place and re-arm. `paused`: no order rests and none is placed. `stopping`: its orders are being cancelled. `stopped`, `expired` and `failed` are final." }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "cancelled", "expired", "grant_revoked" ] }, { "type": "null" } ], "description": "Why the grid is stopping or ended: `cancelled` by the user, `expired` at `validUntil`, or `grant_revoked`. `null` while it runs or is paused." }, "terms": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "The exact terms the user approved; they never change." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends and its last orders expire." }, "cells": { "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The cell's position, lowest first." }, "low": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell buys at." }, "high": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell sells at." }, "side": { "type": "string", "enum": [ "buy", "sell", "idle" ], "description": "The side the cell's next or current order is on, or `idle` for none." }, "state": { "type": "string", "enum": [ "idle", "pending", "placing", "resting", "stalled" ], "description": "`pending`: waits to place. `placing`: an order is being created and funded. `resting`: its order is at the provider. `idle`: places nothing. `stalled`: stopped re-placing after orders ended unfilled too often, or an ending it could not read; the rest of the grid keeps running." }, "order": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's `id`: read it with Get an order for its terms, fills and payouts." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "`buy`: the cell buys its quantity at its low level. `sell`: it sells it at its high level." }, "state": { "type": "string", "enum": [ "prepared", "creating", "created", "signing", "funded", "unconfirmed", "abandoned" ], "description": "Where the order is in our own lifecycle: prepared through funded, unconfirmed or abandoned." }, "fillStatus": { "anyOf": [ { "type": "string", "enum": [ "AWAITING_DEPOSIT", "PENDING_CANCEL", "UNTRIGGERED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "EXPIRED" ] }, { "type": "null" } ], "description": "What the provider last reported about matching, or `null` until it was read." } }, "required": [ "id", "side", "state", "fillStatus" ], "description": "The order the cell has resting or being placed now." }, { "type": "null" } ], "description": "The order the cell rests or is placing now, or `null` when it has none." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times the cell bought at its low level and then sold at its high level." }, "realizedQuoteRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What those cycles earned, in the quote asset's smallest unit: each sale's received amount less its buy's cost." } }, "required": [ "index", "low", "high", "side", "state", "order", "cycles", "realizedQuoteRaw" ], "description": "One cell of the grid: the span between two adjacent levels." }, "description": "Every cell of the grid, lowest first." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Completed buy-then-sell cycles across every cell." }, "realizedProfit": { "type": "object", "properties": { "raw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "In the quote asset's smallest unit." }, "decimal": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The same amount in whole units of the asset, as an exact plain decimal." } }, "required": [ "raw", "decimal" ], "description": "What the completed cycles earned, in the quote asset." }, "heldBaseRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The base the grid's filled buys hold for its sell cells, in the base asset's smallest unit. It stays in the agent wallet when the grid ends." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation in which the user approved the grid." }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that created the grid." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid or one of its cells last changed." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the grid ended, or `null`." } }, "required": [ "id", "state", "stopReason", "terms", "validUntil", "cells", "cycles", "realizedProfit", "heldBaseRaw", "conversationId", "approvalId", "createdAt", "updatedAt", "endedAt" ], "description": "A grid of resting limit orders across a price range: its approved terms, each cell's live order, completed cycles and realized profit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Pause a grid 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. `POST /v1/users/{userId}/wallet/grids/{gridId}/pause` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "gridId", "required": true, "description": "The grid's `id`." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/grids/YOUR_GRID_ID/pause' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The grid, updated. ```json { "description": "The grid, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grid" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `grid_not_active` — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands ```json { "description": "The operation lost to the current state.\n\n- `grid_not_active` — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 410 The resource still exists and stays readable, but can no longer take this request. - `grid_ended` — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat ```json { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `grid_ended` — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.pauseGrid", "summary": "Pause a grid", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "gridId", "required": true, "description": "The grid's `id`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The grid, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grid" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `grid_not_active` — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "410": { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `grid_ended` — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Grid": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grid's id." }, "state": { "type": "string", "enum": [ "active", "paused", "stopping", "stopped", "expired", "failed" ], "description": "`active`: cells place and re-arm. `paused`: no order rests and none is placed. `stopping`: its orders are being cancelled. `stopped`, `expired` and `failed` are final." }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "cancelled", "expired", "grant_revoked" ] }, { "type": "null" } ], "description": "Why the grid is stopping or ended: `cancelled` by the user, `expired` at `validUntil`, or `grant_revoked`. `null` while it runs or is paused." }, "terms": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "The exact terms the user approved; they never change." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends and its last orders expire." }, "cells": { "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The cell's position, lowest first." }, "low": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell buys at." }, "high": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell sells at." }, "side": { "type": "string", "enum": [ "buy", "sell", "idle" ], "description": "The side the cell's next or current order is on, or `idle` for none." }, "state": { "type": "string", "enum": [ "idle", "pending", "placing", "resting", "stalled" ], "description": "`pending`: waits to place. `placing`: an order is being created and funded. `resting`: its order is at the provider. `idle`: places nothing. `stalled`: stopped re-placing after orders ended unfilled too often, or an ending it could not read; the rest of the grid keeps running." }, "order": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's `id`: read it with Get an order for its terms, fills and payouts." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "`buy`: the cell buys its quantity at its low level. `sell`: it sells it at its high level." }, "state": { "type": "string", "enum": [ "prepared", "creating", "created", "signing", "funded", "unconfirmed", "abandoned" ], "description": "Where the order is in our own lifecycle: prepared through funded, unconfirmed or abandoned." }, "fillStatus": { "anyOf": [ { "type": "string", "enum": [ "AWAITING_DEPOSIT", "PENDING_CANCEL", "UNTRIGGERED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "EXPIRED" ] }, { "type": "null" } ], "description": "What the provider last reported about matching, or `null` until it was read." } }, "required": [ "id", "side", "state", "fillStatus" ], "description": "The order the cell has resting or being placed now." }, { "type": "null" } ], "description": "The order the cell rests or is placing now, or `null` when it has none." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times the cell bought at its low level and then sold at its high level." }, "realizedQuoteRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What those cycles earned, in the quote asset's smallest unit: each sale's received amount less its buy's cost." } }, "required": [ "index", "low", "high", "side", "state", "order", "cycles", "realizedQuoteRaw" ], "description": "One cell of the grid: the span between two adjacent levels." }, "description": "Every cell of the grid, lowest first." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Completed buy-then-sell cycles across every cell." }, "realizedProfit": { "type": "object", "properties": { "raw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "In the quote asset's smallest unit." }, "decimal": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The same amount in whole units of the asset, as an exact plain decimal." } }, "required": [ "raw", "decimal" ], "description": "What the completed cycles earned, in the quote asset." }, "heldBaseRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The base the grid's filled buys hold for its sell cells, in the base asset's smallest unit. It stays in the agent wallet when the grid ends." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation in which the user approved the grid." }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that created the grid." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid or one of its cells last changed." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the grid ended, or `null`." } }, "required": [ "id", "state", "stopReason", "terms", "validUntil", "cells", "cycles", "realizedProfit", "heldBaseRaw", "conversationId", "approvalId", "createdAt", "updatedAt", "endedAt" ], "description": "A grid of resting limit orders across a price range: its approved terms, each cell's live order, completed cycles and realized profit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Resume a grid 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. `POST /v1/users/{userId}/wallet/grids/{gridId}/resume` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "gridId", "required": true, "description": "The grid's `id`." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/grids/YOUR_GRID_ID/resume' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The grid, updated. ```json { "description": "The grid, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grid" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `grid_trading_disabled` — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `grid_trading_disabled` — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `grid_not_paused` — the grid is not paused, so there is nothing to resume. Read the grid for where it stands ```json { "description": "The operation lost to the current state.\n\n- `grid_not_paused` — the grid is not paused, so there is nothing to resume. Read the grid for where it stands", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 410 The resource still exists and stays readable, but can no longer take this request. - `grid_ended` — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat ```json { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `grid_ended` — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.resumeGrid", "summary": "Resume a grid", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "gridId", "required": true, "description": "The grid's `id`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The grid, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grid" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `grid_trading_disabled` — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `grid_not_paused` — the grid is not paused, so there is nothing to resume. Read the grid for where it stands", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "410": { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `grid_ended` — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Grid": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grid's id." }, "state": { "type": "string", "enum": [ "active", "paused", "stopping", "stopped", "expired", "failed" ], "description": "`active`: cells place and re-arm. `paused`: no order rests and none is placed. `stopping`: its orders are being cancelled. `stopped`, `expired` and `failed` are final." }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "cancelled", "expired", "grant_revoked" ] }, { "type": "null" } ], "description": "Why the grid is stopping or ended: `cancelled` by the user, `expired` at `validUntil`, or `grant_revoked`. `null` while it runs or is paused." }, "terms": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "The exact terms the user approved; they never change." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends and its last orders expire." }, "cells": { "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The cell's position, lowest first." }, "low": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell buys at." }, "high": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell sells at." }, "side": { "type": "string", "enum": [ "buy", "sell", "idle" ], "description": "The side the cell's next or current order is on, or `idle` for none." }, "state": { "type": "string", "enum": [ "idle", "pending", "placing", "resting", "stalled" ], "description": "`pending`: waits to place. `placing`: an order is being created and funded. `resting`: its order is at the provider. `idle`: places nothing. `stalled`: stopped re-placing after orders ended unfilled too often, or an ending it could not read; the rest of the grid keeps running." }, "order": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's `id`: read it with Get an order for its terms, fills and payouts." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "`buy`: the cell buys its quantity at its low level. `sell`: it sells it at its high level." }, "state": { "type": "string", "enum": [ "prepared", "creating", "created", "signing", "funded", "unconfirmed", "abandoned" ], "description": "Where the order is in our own lifecycle: prepared through funded, unconfirmed or abandoned." }, "fillStatus": { "anyOf": [ { "type": "string", "enum": [ "AWAITING_DEPOSIT", "PENDING_CANCEL", "UNTRIGGERED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "EXPIRED" ] }, { "type": "null" } ], "description": "What the provider last reported about matching, or `null` until it was read." } }, "required": [ "id", "side", "state", "fillStatus" ], "description": "The order the cell has resting or being placed now." }, { "type": "null" } ], "description": "The order the cell rests or is placing now, or `null` when it has none." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times the cell bought at its low level and then sold at its high level." }, "realizedQuoteRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What those cycles earned, in the quote asset's smallest unit: each sale's received amount less its buy's cost." } }, "required": [ "index", "low", "high", "side", "state", "order", "cycles", "realizedQuoteRaw" ], "description": "One cell of the grid: the span between two adjacent levels." }, "description": "Every cell of the grid, lowest first." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Completed buy-then-sell cycles across every cell." }, "realizedProfit": { "type": "object", "properties": { "raw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "In the quote asset's smallest unit." }, "decimal": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The same amount in whole units of the asset, as an exact plain decimal." } }, "required": [ "raw", "decimal" ], "description": "What the completed cycles earned, in the quote asset." }, "heldBaseRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The base the grid's filled buys hold for its sell cells, in the base asset's smallest unit. It stays in the agent wallet when the grid ends." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation in which the user approved the grid." }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that created the grid." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid or one of its cells last changed." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the grid ended, or `null`." } }, "required": [ "id", "state", "stopReason", "terms", "validUntil", "cells", "cycles", "realizedProfit", "heldBaseRaw", "conversationId", "approvalId", "createdAt", "updatedAt", "endedAt" ], "description": "A grid of resting limit orders across a price range: its approved terms, each cell's live order, completed cycles and realized profit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Cancel a grid 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. `POST /v1/users/{userId}/wallet/grids/{gridId}/cancel` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "gridId", "required": true, "description": "The grid's `id`." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/wallet/grids/YOUR_GRID_ID/cancel' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The grid, updated. ```json { "description": "The grid, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grid" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `grid_not_active` — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands ```json { "description": "The operation lost to the current state.\n\n- `grid_not_active` — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 410 The resource still exists and stays readable, but can no longer take this request. - `grid_ended` — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat ```json { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `grid_ended` — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "wallets.cancelGrid", "summary": "Cancel a grid", "tags": [ "wallets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "gridId", "required": true, "description": "The grid's `id`." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The grid, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Grid" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `grid_not_active` — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "410": { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `grid_ended` — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Grid": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The grid's id." }, "state": { "type": "string", "enum": [ "active", "paused", "stopping", "stopped", "expired", "failed" ], "description": "`active`: cells place and re-arm. `paused`: no order rests and none is placed. `stopping`: its orders are being cancelled. `stopped`, `expired` and `failed` are final." }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "cancelled", "expired", "grant_revoked" ] }, { "type": "null" } ], "description": "Why the grid is stopping or ended: `cancelled` by the user, `expired` at `validUntil`, or `grant_revoked`. `null` while it runs or is paused." }, "terms": { "type": "object", "properties": { "base": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact base asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset the grid buys low and sells high." }, "quote": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact quote asset: token id and decimals." } }, "required": [ "pinned" ], "description": "The asset prices are in and buys are paid with." }, "levels": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$" }, "description": "The 2 to 20 grid prices, strictly ascending: quote units per ONE base unit, plain human decimals." }, "quantityPerCell": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact base amount every cell buys and sells, in the base asset's smallest unit. Fixed: profits never compound." }, "cells": { "minItems": 1, "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "enum": [ "buy", "idle" ], "description": "The side the cell's first order is on: buy at its low level, or idle (the cell never places)." } }, "required": [ "start" ] }, "description": "One entry per cell, lowest first (levels.length - 1 of them): cells wholly below the start price and the one straddling it buy, cells wholly above it stay idle." } }, "required": [ "base", "quote", "levels", "quantityPerCell", "cells" ], "description": "The exact terms the user approved; they never change." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid ends and its last orders expire." }, "cells": { "maxItems": 19, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The cell's position, lowest first." }, "low": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell buys at." }, "high": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d{0,38})(\\.\\d{1,38})?$", "description": "The level the cell sells at." }, "side": { "type": "string", "enum": [ "buy", "sell", "idle" ], "description": "The side the cell's next or current order is on, or `idle` for none." }, "state": { "type": "string", "enum": [ "idle", "pending", "placing", "resting", "stalled" ], "description": "`pending`: waits to place. `placing`: an order is being created and funded. `resting`: its order is at the provider. `idle`: places nothing. `stalled`: stopped re-placing after orders ended unfilled too often, or an ending it could not read; the rest of the grid keeps running." }, "order": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's `id`: read it with Get an order for its terms, fills and payouts." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "`buy`: the cell buys its quantity at its low level. `sell`: it sells it at its high level." }, "state": { "type": "string", "enum": [ "prepared", "creating", "created", "signing", "funded", "unconfirmed", "abandoned" ], "description": "Where the order is in our own lifecycle: prepared through funded, unconfirmed or abandoned." }, "fillStatus": { "anyOf": [ { "type": "string", "enum": [ "AWAITING_DEPOSIT", "PENDING_CANCEL", "UNTRIGGERED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "EXPIRED" ] }, { "type": "null" } ], "description": "What the provider last reported about matching, or `null` until it was read." } }, "required": [ "id", "side", "state", "fillStatus" ], "description": "The order the cell has resting or being placed now." }, { "type": "null" } ], "description": "The order the cell rests or is placing now, or `null` when it has none." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times the cell bought at its low level and then sold at its high level." }, "realizedQuoteRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What those cycles earned, in the quote asset's smallest unit: each sale's received amount less its buy's cost." } }, "required": [ "index", "low", "high", "side", "state", "order", "cycles", "realizedQuoteRaw" ], "description": "One cell of the grid: the span between two adjacent levels." }, "description": "Every cell of the grid, lowest first." }, "cycles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Completed buy-then-sell cycles across every cell." }, "realizedProfit": { "type": "object", "properties": { "raw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "In the quote asset's smallest unit." }, "decimal": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The same amount in whole units of the asset, as an exact plain decimal." } }, "required": [ "raw", "decimal" ], "description": "What the completed cycles earned, in the quote asset." }, "heldBaseRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The base the grid's filled buys hold for its sell cells, in the base asset's smallest unit. It stays in the agent wallet when the grid ends." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation in which the user approved the grid." }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval that created the grid." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the grid or one of its cells last changed." }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the grid ended, or `null`." } }, "required": [ "id", "state", "stopReason", "terms", "validUntil", "cells", "cycles", "realizedProfit", "heldBaseRaw", "conversationId", "approvalId", "createdAt", "updatedAt", "endedAt" ], "description": "A grid of resting limit orders across a price range: its approved terms, each cell's live order, completed cycles and realized profit." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get portfolio 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 /v1/users/{userId}/portfolio` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/portfolio' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 Everything the agent owns right now, by account and by holding. ```json { "description": "Everything the agent owns right now, by account and by holding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Portfolio" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "portfolio.get", "summary": "Get portfolio", "tags": [ "portfolio" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "Everything the agent owns right now, by account and by holding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Portfolio" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Portfolio": { "type": "object", "properties": { "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The moment these figures value the portfolio at." }, "totalUsdMicros": { "type": "string", "maxLength": 164, "pattern": "^(0|[1-9]\\d*)$", "description": "What every account is worth together, in millionths of a US dollar: the sum of the accounts' `valueUsdMicros`. Holdings in `excluded` are not counted. It equals the last point of Get portfolio history." }, "provisional": { "type": "boolean", "description": "True when any account is: part of the total has not yet been confirmed against its custodian. Show the figure and say it is unconfirmed." }, "accounts": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string", "enum": [ "wallet", "orders", "solana", "polymarket", "perps", "transit" ], "description": "Which account: `wallet` (the agent wallet), `orders` (funds held by its open limit orders), `solana`, `polymarket`, `perps`, or `transit` (money on its way from one of these accounts to another)." }, "valueUsdMicros": { "type": "string", "maxLength": 164, "pattern": "^(0|[1-9]\\d*)$", "description": "What this account's priced holdings are worth, in millionths of a US dollar." }, "confirmedThrough": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this account's holdings last matched a read from its custodian; null before the first match." }, "provisional": { "type": "boolean", "description": "True when the value includes changes after `confirmedThrough` that the next custodian read has not yet confirmed." } }, "required": [ "account", "valueUsdMicros", "confirmedThrough", "provisional" ] }, "description": "Each account the agent has opened, once." }, "holdings": { "maxItems": 10000, "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string", "enum": [ "wallet", "orders", "solana", "polymarket", "perps", "transit" ], "description": "Which account: `wallet` (the agent wallet), `orders` (funds held by its open limit orders), `solana`, `polymarket`, `perps`, or `transit` (money on its way from one of these accounts to another)." }, "asset": { "$ref": "#/components/schemas/PortfolioAssetRef" }, "symbol": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ], "description": "The asset's ticker symbol; null when no source names it, as for a Polymarket outcome. Show your own label then." }, "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ], "description": "The asset's name, when known." }, "iconUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "pattern": "^(https:\\/\\/\\S+|\\/v1\\/solana\\/tokens\\/[1-9A-HJ-NP-Za-km-z]{32,44}\\/icon)$" }, { "type": "null" } ], "description": "Where to load the asset's icon: an https URL, or for a Solana token the path of Get a token icon on this API. Null when none is known; draw a placeholder." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "How many decimal places `amountRaw` carries." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "How much the account holds, in the asset's smallest unit; scale by `decimals` for a human amount." }, "price": { "anyOf": [ { "type": "object", "properties": { "usd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The price of one whole unit, in US dollars, as an exact decimal string." }, "status": { "type": "string", "enum": [ "priced", "carried", "last_trade" ], "description": "How the price was found: `priced` (a recent market price), `carried` (the last market price, up to 24 hours old) or `last_trade` (the user's own last trade of it, when no market prices it)." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "status", "pricedAt" ] }, { "type": "null" } ], "description": "The price this holding is valued at; null when nothing prices it, and the holding is then listed in `excluded`." }, "valueUsdMicros": { "anyOf": [ { "type": "string", "maxLength": 164, "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ], "description": "What the holding is worth, in millionths of a US dollar; null when `price` is null. A null value is left out of the total, never counted as zero." }, "priceChange24hBps": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How the price moved over the last 24 hours, in basis points; null when either price is unknown." }, "averageCostUsd": { "anyOf": [ { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, { "type": "null" } ], "description": "What the units held cost on average, per whole unit, in US dollars, from the user's own buys; null when none of the holding was bought." } }, "required": [ "account", "asset", "symbol", "name", "iconUrl", "decimals", "amountRaw", "price", "valueUsdMicros", "priceChange24hBps", "averageCostUsd" ] }, "description": "Each asset each account holds, most valuable first; unpriced holdings last." }, "excluded": { "maxItems": 10000, "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string", "enum": [ "wallet", "orders", "solana", "polymarket", "perps", "transit" ], "description": "Which account: `wallet` (the agent wallet), `orders` (funds held by its open limit orders), `solana`, `polymarket`, `perps`, or `transit` (money on its way from one of these accounts to another)." }, "asset": { "$ref": "#/components/schemas/PortfolioAssetRef" }, "reason": { "type": "string", "enum": [ "no_price" ], "description": "Why it is not counted: `no_price`, nothing prices it." } }, "required": [ "account", "asset", "reason" ] }, "description": "The holdings left out of the total, and why. Say the total leaves them out rather than reading them as worth zero." } }, "required": [ "asOf", "totalUsdMicros", "provisional", "accounts", "holdings", "excluded" ], "description": "Everything the agent owns right now: the total, each account, and each holding with its price and value." }, "PortfolioAssetRef": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "token" }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset's `assetId`, as Get balances and the wallet's other routes name it." } }, "required": [ "kind", "assetId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana" }, "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The Solana token's mint address." } }, "required": [ "kind", "mint" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Native SOL in the agent's Solana account, which has no mint of its own." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "polymarket" }, "tokenId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$", "description": "The outcome token's id, the `assetId` a prediction order and Get prediction account name." } }, "required": [ "kind", "tokenId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "usd", "description": "US dollars: perps account equity, or Polymarket's pUSD." } }, "required": [ "kind" ] } ], "description": "Which asset a portfolio row is: `token` (an agent wallet asset), `solana` (a token by its mint), `sol` (native SOL), `polymarket` (an outcome's shares) or `usd`." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get portfolio history 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. `GET /v1/users/{userId}/portfolio/history` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "default": "1D", "type": "string", "enum": [ "1D", "1W", "1M", "3M", "1Y", "all" ] }, "in": "query", "name": "range", "required": false, "description": "How far back to draw: `1D` (the default, a point every 5 minutes), `1W` (hourly), `1M` (every 4 hours), `3M` and `1Y` (daily), or `all`, daily from the first activity, a few days apart once that is more than 400 days ago." }, { "schema": { "type": "string", "enum": [ "5m", "1h", "1d" ] }, "in": "query", "name": "step", "required": false, "description": "Space the points this far apart instead: `5m`, `1h` or `1d`. It cannot be finer than the range is kept at: `5m` only on `1D`, `1h` on `1D`, `1W` and `1M`, and `1d` on any range." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/portfolio/history' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The value over the range, its gain, and the money in and out. ```json { "description": "The value over the range, its gain, and the money in and out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortfolioHistory" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "portfolio.history", "summary": "Get portfolio history", "tags": [ "portfolio" ], "description": "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.", "parameters": [ { "schema": { "default": "1D", "type": "string", "enum": [ "1D", "1W", "1M", "3M", "1Y", "all" ] }, "in": "query", "name": "range", "required": false, "description": "How far back to draw: `1D` (the default, a point every 5 minutes), `1W` (hourly), `1M` (every 4 hours), `3M` and `1Y` (daily), or `all`, daily from the first activity, a few days apart once that is more than 400 days ago." }, { "schema": { "type": "string", "enum": [ "5m", "1h", "1d" ] }, "in": "query", "name": "step", "required": false, "description": "Space the points this far apart instead: `5m`, `1h` or `1d`. It cannot be finer than the range is kept at: `5m` only on `1D`, `1h` on `1D`, `1W` and `1M`, and `1d` on any range." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The value over the range, its gain, and the money in and out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortfolioHistory" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "PortfolioHistory": { "type": "object", "properties": { "step": { "type": "string", "pattern": "^(5m|1h|4h|[1-9]\\d{0,3}d)$", "description": "How far apart the points are: `5m`, `1h`, `4h`, `1d`, or a number of days (such as `3d`) for a long `all`." }, "points": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The moment this point values the portfolio at." }, "valueUsdMicros": { "type": "string", "maxLength": 164, "pattern": "^(0|[1-9]\\d*)$", "description": "What everything was worth then, in millionths of a US dollar, counting the holdings that had a price." }, "gainUsdMicros": { "type": "string", "maxLength": 165, "pattern": "^(0|-?[1-9]\\d*)$", "description": "The gain from the range's first point through this one, in millionths of a US dollar: the change in value less money in plus money out. A holding entering or leaving the valued set is not gain." }, "provisional": { "type": "boolean", "description": "True when this point includes changes not yet confirmed against a custodian, or values a holding at a carried price." }, "marks": { "description": "What changed at this point that is not gain; absent when nothing did.", "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "coverage_in", "coverage_out", "unexplained" ], "description": "`coverage_in`: a holding started being valued here; `coverage_out`: it stopped (it lost its price); `unexplained`: a change no deposit, withdrawal or trade explains landed here and counts as money in or out." }, "asset": { "$ref": "#/components/schemas/PortfolioAssetRef" } }, "required": [ "kind", "asset" ] } } }, "required": [ "at", "valueUsdMicros", "gainUsdMicros", "provisional" ] }, "description": "The value over the range, oldest first. The last point is `asOf` and equals Get portfolio's total." }, "summary": { "type": "object", "properties": { "changeUsdMicros": { "type": "string", "maxLength": 165, "pattern": "^(0|-?[1-9]\\d*)$", "description": "How much the value changed over the range: the last point less the first, in millionths of a US dollar." }, "moneyInUsdMicros": { "type": "string", "maxLength": 164, "pattern": "^(0|[1-9]\\d*)$", "description": "Money that came in from outside during the range, in millionths of a US dollar: deposits, transfers in and unexplained arrivals. Moves between the agent's own accounts are not counted." }, "moneyOutUsdMicros": { "type": "string", "maxLength": 164, "pattern": "^(0|[1-9]\\d*)$", "description": "Money that left for outside during the range, in millionths of a US dollar: withdrawals, transfers out and unexplained departures. Moves between the agent's own accounts are not counted." }, "gainUsdMicros": { "type": "string", "maxLength": 165, "pattern": "^(0|-?[1-9]\\d*)$", "description": "The change that was not money in or out, in millionths of a US dollar: the last point's `gainUsdMicros`." }, "gainBps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The gain as a share of the first point's value plus the money in, in basis points, truncated; 0 when both are 0." } }, "required": [ "changeUsdMicros", "moneyInUsdMicros", "moneyOutUsdMicros", "gainUsdMicros", "gainBps" ], "description": "The range at a glance." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The last moment this history represents." } }, "required": [ "step", "points", "summary", "asOf" ], "description": "Everything the agent owns, valued over a range, with how much of the change was gain." }, "PortfolioAssetRef": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "token" }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset's `assetId`, as Get balances and the wallet's other routes name it." } }, "required": [ "kind", "assetId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solana" }, "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The Solana token's mint address." } }, "required": [ "kind", "mint" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Native SOL in the agent's Solana account, which has no mint of its own." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "polymarket" }, "tokenId": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,77})$", "description": "The outcome token's id, the `assetId` a prediction order and Get prediction account name." } }, "required": [ "kind", "tokenId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "usd", "description": "US dollars: perps account equity, or Polymarket's pUSD." } }, "required": [ "kind" ] } ], "description": "Which asset a portfolio row is: `token` (an agent wallet asset), `solana` (a token by its mint), `sol` (native SOL), `polymarket` (an outcome's shares) or `usd`." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List activity 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. `GET /v1/users/{userId}/activity` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "How many items to return, at most 50." }, { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "The `nextCursor` from the previous page; omit for the newest items." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "trade", "swap", "withdrawal", "deposit", "deposit_address", "automation", "solana", "solana_sell_many", "solana_trade" ] }, { "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "trade", "swap", "withdrawal", "deposit", "deposit_address", "automation", "solana", "solana_sell_many", "solana_trade" ] } } ] }, "in": "query", "name": "type", "required": false, "description": "Keep only these kinds of item; repeat it for several (`type=trade&type=deposit`). Omit for every kind." }, { "schema": { "type": "string", "enum": [ "conversation", "automation" ] }, "in": "query", "name": "origin", "required": false, "description": "Keep only trades, and Solana trades and transfers, the agent asked for in a chat (`conversation`) or in an automation's run (`automation`, which also keeps changes to automations). The user's own swaps, deposits, deposit addresses and withdrawals are left out when this is set." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/activity' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of activity, and how many approvals are waiting. ```json { "description": "A page of activity, and how many approvals are waiting.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" }, "description": "This page of activity, newest first." }, "nextCursor": { "description": "Pass it back as `cursor` for older items; null at the end.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals are waiting for the user, across every conversation." } }, "required": [ "data", "nextCursor", "pendingApprovals" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "activity.list", "summary": "List activity", "tags": [ "activity" ], "description": "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.", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "How many items to return, at most 50." }, { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "The `nextCursor` from the previous page; omit for the newest items." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "trade", "swap", "withdrawal", "deposit", "deposit_address", "automation", "solana", "solana_sell_many", "solana_trade" ] }, { "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "trade", "swap", "withdrawal", "deposit", "deposit_address", "automation", "solana", "solana_sell_many", "solana_trade" ] } } ] }, "in": "query", "name": "type", "required": false, "description": "Keep only these kinds of item; repeat it for several (`type=trade&type=deposit`). Omit for every kind." }, { "schema": { "type": "string", "enum": [ "conversation", "automation" ] }, "in": "query", "name": "origin", "required": false, "description": "Keep only trades, and Solana trades and transfers, the agent asked for in a chat (`conversation`) or in an automation's run (`automation`, which also keeps changes to automations). The user's own swaps, deposits, deposit addresses and withdrawals are left out when this is set." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of activity, and how many approvals are waiting.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" }, "description": "This page of activity, newest first." }, "nextCursor": { "description": "Pass it back as `cursor` for older items; null at the end.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals are waiting for the user, across every conversation." } }, "required": [ "data", "nextCursor", "pendingApprovals" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "ActivityItem": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The item's id: the trade, swap, withdrawal, deposit, deposit address, Solana operation or Solana trade id, or the automation change's own id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened: the request, or the change. The feed is ordered by it." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed, such as a settlement or a credit." }, "kind": { "type": "string", "const": "trade", "description": "A trade; read `trade`." }, "trade": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation in which the agent asked for this trade." }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "Where the trade was asked for: an ordinary chat, or a conversation an automation started." }, "title": { "description": "The conversation's current title; null for an untitled conversation.", "type": [ "string", "null" ] }, "assetIds": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 512 }, "additionalProperties": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "description": "Maps the explicit Intents protocol assets in this trade to opaque Fin holdings identities, for joining portfolio metadata and prices." }, "approval": { "description": "The request's exact human review, when one was required; absent when it runs under an automation's standing permission.", "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The exact single-use review bound to this financial request." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The recorded human decision, with overdue pending reviews shown as expired; approval alone does not prove execution." }, "contract": { "description": "The exact reviewed financial terms, when retained and readable.", "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, "expiresAt": { "description": "When the exact review ceases to authorize an execution claim.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "executionRestriction": { "description": "The immutable restriction that prevents automatic signing under this approval.", "type": "string", "const": "signing_disabled" } }, "required": [ "approvalId", "status" ] }, "automationRunId": { "description": "The automation run that asked for this trade, when one did.", "type": "string", "minLength": 1, "maxLength": 160 }, "request": { "anyOf": [ { "type": "object", "properties": { "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact input asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request spends; it must match the approved action at this position." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact output asset's token id and decimals." } }, "required": [ "pinned" ], "description": "The concrete asset this request produces; it must match the approved action at this position." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] } ] }, "description": "The complete ordered financial actions proposed for this execution, with concrete assets and exact quantity rules." }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The explicit loss and signature-lifetime limits; these must exactly match the approved grant." }, "execution": { "description": "Required on every new chat proposal: the exact execution limits proposed for approval. Copy existing signed grants unchanged; historical approvals and standing grants with this field omitted retain their original execution behavior.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "actions", "bounds" ] }, { "type": "null" } ], "description": "What the agent asked for: the actions and their limits, as swaps and payouts to the destination the user approved, the same as Get a trade returns. A leg's `actionIndex` names its action, so a payout can be shown as one. `null` only for old trades recorded without it." }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position in the frozen plan, counting from zero." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "Which of the trade's `request.actions` this leg carries out, counting from zero: a swap, or a payout to the user's main wallet or to an address they approved." }, "inputPriceUsd": { "description": "The USD price of one whole input token that the plan was checked against, as plain decimal text; absent on plans that recorded none.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "outputPriceUsd": { "description": "The USD price of one whole output token that the plan was checked against, as plain decimal text; absent on plans that recorded none.", "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$" }, "input": { "description": "The frozen input asset and requested amount when that side was fixed; not measured spend.", "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ] }, "output": { "description": "The frozen output asset and requested amount when that side was fixed; not measured proceeds.", "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ] }, "minimumOutputRaw": { "description": "The minimum output required by an exact-input leg, in the output asset's smallest unit.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "maximumInputRaw": { "description": "The maximum input permitted by an exact-output leg, in the input asset's smallest unit.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "stage": { "description": "The stage derived from the persisted claim while it has no terminal receipt; absent for untouched planned legs.", "type": "string", "enum": [ "checking", "retrying", "quoting", "signed", "confirming", "unresolved" ] }, "legId": { "description": "The actual claim's durable ID; absent when this planned leg was never attempted.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "receipt": { "description": "The retained terminal evidence for the actual leg; untouched planned legs have no receipt.", "oneOf": [ { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current receipts use `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "settled", "description": "The leg settled: its output asset moved as planned." }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What the leg produced." } }, "required": [ "approvalId", "legId", "index", "state", "output" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current receipts use `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "refunded", "description": "The leg did not settle and its input asset was returned." }, "refund": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEP-141 token id." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "description": "The amount, in the token's smallest unit, when it is known.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals" ], "description": "What was returned." } }, "required": [ "approvalId", "legId", "index", "state", "refund" ] }, { "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "legId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Which leg of the plan this receipt settles." }, "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "This leg's position within the plan, counting from zero." }, "operationId": { "description": "The durable financial request this evidence belongs to.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "occurrenceId": { "description": "The archived event's original identity, retained verbatim; current receipts use `operationId`.", "type": "string", "minLength": 1, "maxLength": 160 }, "state": { "type": "string", "const": "not_executed", "description": "The leg did not settle. Most reasons mean it never reached the provider; `rejected` means it did and was refused there — see `reason`." }, "reason": { "description": "Why nothing executed: `signing_disabled` when automatic signing was off, `signing_failed` when signing itself failed, `rejected` when the provider refused the submission outright (it did reach the provider), `expired` when the leg's own signing/deposit window elapsed before a terminal fact arrived, or `failed` otherwise. Optional so receipts written before the reason was carried still parse.", "type": "string", "enum": [ "signing_disabled", "signing_failed", "rejected", "expired", "failed" ] }, "unsignedBy": { "description": "Present with `signing_failed` on an Agent API wallet's leg when the NEAR Intents Agent API, the wallet's signer, released no signature for it: it refused the request, or its own history proves it released none. Nothing moved.", "type": "string", "const": "agent_api" } }, "required": [ "approvalId", "legId", "index", "state" ] } ] } }, "required": [ "index", "actionIndex" ] }, "description": "Every leg of the frozen plan in plan order, including untouched legs without claims or receipts; empty before a plan exists." }, "result": { "description": "The persisted outcome, updated by conclusive receipts; absent while no outcome exists, including denied or expired preparation.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed", "failed", "denied", "unverified", "pending", "partial", "no_trade", "settled", "refunded", "not_executed" ], "description": "The canonical financial outcome projected for display; refused requests appear as denied, pending is unresolved and partial means only part executed." }, "reason": { "description": "Present when automatic signing was disabled for the reported non-execution.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial result whose run refused a later leg before it was claimed: the planned action it stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "message": { "description": "The host's fixed explanation for a refused request, when present; never raw provider text.", "type": "string", "maxLength": 280 }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The reported leg's position in the frozen plan, counting from zero." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The retained execution or settlement state for this reported leg." } }, "required": [ "index", "state" ] }, "description": "The actual legs represented by this outcome; untouched planned legs are not fabricated as results." } }, "required": [ "status", "legs" ] }, "running": { "type": "boolean", "description": "True when the trade has an execution claim and no current outcome; it does not prove a process is still running." }, "ended": { "type": "boolean", "description": "True when no outcome is available and the trade is uncertain, denied or expired. Later receipts may resolve uncertainty; this does not assert that settlement is final." } }, "required": [ "conversationId", "origin", "title", "assetIds", "request", "legs", "running", "ended" ], "description": "The trade the agent asked for, in a chat or in an automation's run." } }, "required": [ "id", "createdAt", "updatedAt", "kind", "trade" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The item's id: the trade, swap, withdrawal, deposit, deposit address, Solana operation or Solana trade id, or the automation change's own id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened: the request, or the change. The feed is ordered by it." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed, such as a settlement or a credit." }, "kind": { "type": "string", "const": "swap", "description": "A swap the user made in the agent wallet with Swap tokens; read `swap`." }, "swap": { "$ref": "#/components/schemas/Swap" } }, "required": [ "id", "createdAt", "updatedAt", "kind", "swap" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The item's id: the trade, swap, withdrawal, deposit, deposit address, Solana operation or Solana trade id, or the automation change's own id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened: the request, or the change. The feed is ordered by it." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed, such as a settlement or a credit." }, "kind": { "type": "string", "const": "withdrawal", "description": "A withdrawal; read `withdrawal`." }, "withdrawal": { "$ref": "#/components/schemas/Withdrawal" } }, "required": [ "id", "createdAt", "updatedAt", "kind", "withdrawal" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The item's id: the trade, swap, withdrawal, deposit, deposit address, Solana operation or Solana trade id, or the automation change's own id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened: the request, or the change. The feed is ordered by it." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed, such as a settlement or a credit." }, "kind": { "type": "string", "const": "deposit", "description": "A deposit; read `deposit`." }, "deposit": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` the deposit was created with; filter List deposits on it." }, "terms": { "description": "The terms the deposit was created with.", "$ref": "#/components/schemas/DepositTerms" }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `failed` means no address was issued. `expired` means the deadline passed with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "rail": { "type": "string", "const": "chain", "description": "Payment originates on the specified native blockchain." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "const": false, "description": "Bound to one funding request; never reuse for a later transfer." }, "kind": { "type": "string", "const": "chain_transfer", "description": "The external wallet broadcasts a native-chain transfer using these instructions." } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind" ] }, { "type": "object", "properties": { "rail": { "type": "string", "const": "intents", "description": "Payment originates on the specified public or confidential Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "Exact asset and atomic-unit precision to transfer." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Verified destination for this deposit request only." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact funding amount in asset atomic units." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Minimum authorized wallet credit." }, "expectedCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Quoted credit; the receipt records actual credit separately." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Do not initiate another transfer after this deadline." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Provider deposit deadline. Late payment remains observable; expiry never proves a refund." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "reusable": { "type": "boolean", "const": false, "description": "Bound to one funding request; never reuse for a later transfer." }, "kind": { "type": "string", "const": "intents_transfer", "description": "The external wallet signs and submits a transfer intent on the specified ledger." }, "protocol": { "type": "object", "properties": { "verifier": { "type": "string", "enum": [ "intents.near", "intents.far" ], "description": "Ledger verifier for the external wallet's signed transfer intent." }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Ledger protocol asset identifier, exposed only for explicit advanced Intents funding." }, "depositAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Quote deposit account, used by the external wallet to generate the exact signed transfer intent; identical to the instruction address." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact signed transfer amount." } }, "required": [ "verifier", "assetId", "depositAddress", "amountRaw" ], "description": "The external wallet constructs and signs a transfer intent with its own authority. Fin does not sign for or hold credentials to that source wallet." } }, "required": [ "rail", "network", "asset", "address", "memo", "amountRaw", "minimumCreditRaw", "expectedCreditRaw", "sendBefore", "expiresAt", "refundAddress", "reusable", "kind", "protocol" ] } ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When trusted provider evidence was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Provider-established terminal financial outcome." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Observed source amount." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Actual wallet credit; zero on full refund." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Amount refunded to the approved source destination." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed source transactions or ledger intent identifiers bound to the instruction." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Observed refund transactions or ledger intent identifiers." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What was credited or refunded; `null` until that is observed." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit last changed." } }, "required": [ "id", "requestKey", "terms", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ], "description": "The deposit, as Get a deposit returns it." } }, "required": [ "id", "createdAt", "updatedAt", "kind", "deposit" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The item's id: the trade, swap, withdrawal, deposit, deposit address, Solana operation or Solana trade id, or the automation change's own id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened: the request, or the change. The feed is ordered by it." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed, such as a settlement or a credit." }, "kind": { "type": "string", "const": "deposit_address", "description": "A transfer to a one-time deposit address; read `depositAddress`." }, "depositAddress": { "description": "The deposit address, as Get a deposit address returns it: what arrived is in its `receipt`.", "$ref": "#/components/schemas/DepositAddress" } }, "required": [ "id", "createdAt", "updatedAt", "kind", "depositAddress" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The item's id: the trade, swap, withdrawal, deposit, deposit address, Solana operation or Solana trade id, or the automation change's own id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened: the request, or the change. The feed is ordered by it." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed, such as a settlement or a credit." }, "kind": { "type": "string", "const": "automation", "description": "A change to an automation; read `automation`." }, "automation": { "type": "object", "properties": { "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation that changed." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name." }, "change": { "type": "string", "enum": [ "created", "paused", "resumed", "deleted" ], "description": "What happened to it: `created`, `paused`, `resumed` or `deleted` (which includes an automation that finished on its own). Edits are retained privately and shown in chat receipts and automation detail, not in this feed." } }, "required": [ "automationId", "name", "change" ], "description": "The automation and what changed." } }, "required": [ "id", "createdAt", "updatedAt", "kind", "automation" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The item's id: the trade, swap, withdrawal, deposit, deposit address, Solana operation or Solana trade id, or the automation change's own id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened: the request, or the change. The feed is ordered by it." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed, such as a settlement or a credit." }, "kind": { "type": "string", "const": "solana", "description": "A buy or a sell of a Solana token through the agent's own Solana account, or SOL moved into or out of it; read `solana`." }, "solana": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation in which the agent asked for it." }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "Where it was asked for: an ordinary chat, or a conversation an automation started." }, "title": { "description": "The conversation's current title; null for an untitled conversation.", "type": [ "string", "null" ] }, "automationRunId": { "description": "The automation run that asked for it, when one did.", "type": "string", "minLength": 1, "maxLength": 160 }, "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "request": { "anyOf": [ { "$ref": "#/components/schemas/SolanaBuyInput" }, { "$ref": "#/components/schemas/SolanaSellInput" }, { "$ref": "#/components/schemas/SolanaFundInput" }, { "$ref": "#/components/schemas/SolanaWithdrawInput" } ], "description": "What the agent asked for, as the user approved it: a buy's, a sell's, a fund's or a withdrawal's terms, as `side` says." }, "approval": { "description": "The request's own approval, when it needed one; absent when it ran under an automation's standing permission.", "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The single-use approval of this exact request." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The user's recorded decision, with an overdue pending approval shown as expired; an approval alone does not mean it ran." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval stops covering a start." } }, "required": [ "approvalId", "status", "expiresAt" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "partial", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, usually while it waits for the user's approval. `processing` while it runs, or while a Solana transaction it sent, or its transfer back to the agent wallet, has not finished. Then `completed` (the tokens bought, the proceeds of a sale or the SOL moved arrived), `partial` (part of it stands: a buy whose swap never happened after the account was funded, so the SOL is in the agent's Solana account, or a sale whose swap landed but whose transfer back did not finish, or that kept SOL, so the SOL is in the account or with 1Click until it refunds it; `solLeftLamports` says how much the account holds), `refunded` (1Click sent the funds back where they came from) or `failed` (nothing moved; `failureReason` says why). `denied` and `expired` mean the user denied it, or its approval ran out, before it started. `uncertain` means the result could not be confirmed yet: never ask the agent for a replacement, keep checking. `completed`, `partial`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the agent wallet or the Solana account did not hold enough, the account's reserve included. `quote_rejected`: the price or the route failed its checks, the loss limit would have been crossed, or a buy was under the minimum. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the approval no longer covered it, or the token is one the agent does not trade. `stopped`: an operator paused trading or turned the wallet off. `not_executed`: nothing it sent landed before it expired. `signing_disabled`: this deployment does not sign trades. In every case nothing moved." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." } }, "required": [ "conversationId", "origin", "title", "side", "request", "status", "failureReason", "transactions" ], "description": "The Solana trade or transfer the agent asked for, in a chat or in an automation's run." } }, "required": [ "id", "createdAt", "updatedAt", "kind", "solana" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The item's id: the trade, swap, withdrawal, deposit, deposit address, Solana operation or Solana trade id, or the automation change's own id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened: the request, or the change. The feed is ordered by it." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed, such as a settlement or a credit." }, "kind": { "type": "string", "const": "solana_sell_many", "description": "A sale of several Solana tokens under one approval, through the agent's own Solana account; read `solanaSellMany`." }, "solanaSellMany": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation in which the agent asked for it." }, "origin": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "conversation", "description": "An ordinary user-started conversation." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "automation", "description": "A conversation an automation created." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation that created this conversation." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The automation's name at the time this conversation started." } }, "required": [ "type", "automationId", "name" ] } ], "description": "Where it was asked for: an ordinary chat, or a conversation an automation started." }, "title": { "description": "The conversation's current title; null for an untitled conversation.", "type": [ "string", "null" ] }, "automationRunId": { "description": "The automation run that asked for it, when one did.", "type": "string", "minLength": 1, "maxLength": 160 }, "approval": { "description": "The request's own approval, when it needed one; absent when it ran under an automation's standing permission.", "type": "object", "properties": { "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The single-use approval of this exact request." }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired" ], "description": "The user's recorded decision, with an overdue pending approval shown as expired; an approval alone does not mean it ran." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the approval stops covering a start." } }, "required": [ "approvalId", "status", "expiresAt" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "partial", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, usually while it waits for the user's approval. `processing` while it runs, or while a Solana transaction it sent, or its transfer back to the agent wallet, has not finished. Then `completed` (the tokens bought, the proceeds of a sale or the SOL moved arrived), `partial` (part of it stands: a buy whose swap never happened after the account was funded, so the SOL is in the agent's Solana account, or a sale whose swap landed but whose transfer back did not finish, or that kept SOL, so the SOL is in the account or with 1Click until it refunds it; `solLeftLamports` says how much the account holds), `refunded` (1Click sent the funds back where they came from) or `failed` (nothing moved; `failureReason` says why). `denied` and `expired` mean the user denied it, or its approval ran out, before it started. `uncertain` means the result could not be confirmed yet: never ask the agent for a replacement, keep checking. `completed`, `partial`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the agent wallet or the Solana account did not hold enough, the account's reserve included. `quote_rejected`: the price or the route failed its checks, the loss limit would have been crossed, or a buy was under the minimum. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the approval no longer covered it, or the token is one the agent does not trade. `stopped`: an operator paused trading or turned the wallet off. `not_executed`: nothing it sent landed before it expired. `signing_disabled`: this deployment does not sign trades. In every case nothing moved." }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "request": { "description": "The sale as the user approved it: each coin with its exact amount and its own loss bound, in the order they sold, and what they return.", "$ref": "#/components/schemas/SolanaSellManyInput" }, "sales": { "description": "Each coin in the order it ran and what became of it, once the sale's outcome is recorded; `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "conversationId", "origin", "title", "status", "failureReason", "transactions", "request" ], "description": "The sale the agent asked for, in a chat or in an automation's run: each coin as approved, how the sale stands, and what became of each coin." } }, "required": [ "id", "createdAt", "updatedAt", "kind", "solanaSellMany" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The item's id: the trade, swap, withdrawal, deposit, deposit address, Solana operation or Solana trade id, or the automation change's own id." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened: the request, or the change. The feed is ordered by it." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed, such as a settlement or a credit." }, "kind": { "type": "string", "const": "solana_trade", "description": "A buy or a sale of a Solana token the user placed themselves on its page, with Place a Solana trade; read `solanaTrade`." }, "solanaTrade": { "description": "The trade, as Get a Solana trade returns it.", "$ref": "#/components/schemas/SolanaTrade" } }, "required": [ "id", "createdAt", "updatedAt", "kind", "solanaTrade" ] } ], "description": "One thing that happened in the user's wallet or automations. `kind` names the object it carries, which is the same object that resource's own route returns." }, "Swap": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id." }, "terms": { "description": "The terms the user signed.", "$ref": "#/components/schemas/SwapTerms" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, `processing` while it runs, then `completed` (the bought asset is in the agent wallet), `refunded` (the provider sent the sold asset back to the agent wallet) 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. `completed`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount when the swap started. `quote_rejected`: the price at execution failed its checks, or would have received less than `terms.minimumReceivedRaw` or lost more than the loss limit. `quote_expired`: the quote ran out before the provider took the swap. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the signature no longer covered it when it started. `stopped`: an operator paused trading or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign trades. In every case nothing was swapped; get a new quote to try again." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the swap was requested." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the swap started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; `null` before then." }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The provider swap's id." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based position in the swap's plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset it delivered: the bought asset, or the sold one when it was refunded." }, "amountRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The amount actually received (or refunded), in this asset's smallest unit; `null` until a receipt confirms it." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "The number of decimals of this asset's smallest unit." }, "intentHashes": { "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The NEAR Intents ids of the intents that carried out this step, as 1Click reported them when it settled. Quote one to support to trace the step. They are on the confidential NEAR Intents ledger, which no public explorer shows. Empty until the step settles, and for a step that was refunded or did not run." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this swap's outcome was observed." } }, "required": [ "id", "index", "state", "assetId", "amountRaw", "decimals", "intentHashes", "refundReason", "observedAt" ] }, "description": "The swap the provider made and what it delivered, as evidence." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the swap sold (`terms.amountRaw`) was worth when it ran, at the trusted price Fin checked its plan against. `null` before it has a plan, and when no price was recorded." } }, "required": [ "id", "terms", "status", "failureReason", "result", "createdAt", "startedAt", "reportedAt", "receipts", "value" ], "examples": [ { "id": "0d7a9d4e-1f53-4f3b-9d25-1c4e5f8b7a61", "terms": { "sellAssetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "buyAssetId": "asset_3333333333333333333333333333333333333333333333333333333333333333", "minimumReceivedRaw": "331250000000000000000000", "maxValueLossBps": 250 }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ], "description": "A swap in the agent wallet: its terms, its `status`, and the evidence behind it." }, "SwapTerms": { "type": "object", "properties": { "sellAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to sell from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount to sell, in the sold asset's smallest unit." }, "buyAssetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to buy: an `id` from List supported assets. It stays in the agent wallet." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the swap may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet receives of the bought asset, in its smallest unit." } }, "required": [ "sellAssetId", "amountRaw", "buyAssetId", "maxValueLossBps", "minimumReceivedRaw" ], "description": "The exact terms of a swap in the agent wallet: what it sells, what it buys, and the limits it must stay within." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "ValueAtTime": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The value in US dollars as plain decimal text, rounded down to the cent: the amount times `priceUsd`." }, "priceUsd": { "type": "string", "maxLength": 80, "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The USD price of one whole token it was valued at, as plain decimal text." }, "pricedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that price was observed." } }, "required": [ "usd", "priceUsd", "pricedAt" ], "description": "What an amount was worth in US dollars when it moved, and the price it was valued at. Display only: derived on read, never an input to a transfer or a limit." }, "Withdrawal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id." }, "terms": { "anyOf": [ { "$ref": "#/components/schemas/WithdrawalTerms" }, { "type": "null" } ], "description": "The signed terms; `null` only for withdrawals made before terms were recorded." }, "debit": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount taken from the agent wallet, in the asset's smallest unit." } }, "required": [ "assetId", "amountRaw" ], "description": "What leaves the agent wallet: the asset and the exact amount." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`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. `completed`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the wallet did not hold the amount when the withdrawal started. `quote_rejected`: the price at execution failed its checks or fell outside the signed limits. `quote_expired`: the quote ran out before the provider took the transfer. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the signature no longer covered it when it started, or nothing could sign it then (the automation firing it ran for was not confirmed in time, or the owner's own wallet could not be resolved). `stopped`: an operator paused withdrawals or turned the wallet off. `not_executed`: the provider did not carry it out. `signing_disabled`: this deployment does not sign transfers. In every case nothing left the wallet; get a new quote to try again." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The recorded outcome behind `status`, as evidence; `null` until there is one. Read `status` to decide what to do." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the withdrawal was requested." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the withdrawal started; `null` before then." }, "reportedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When its outcome was recorded; `null` before then." }, "receipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The transfer's id." }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based position in the withdrawal plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "One leg's progress: `claimed` (its allowance is reserved, not yet signed), `signed` (signed, not yet submitted), `uncertain` (submitted; the provider's outcome is not yet confirmed), then terminal — `settled`, `refunded`, or `not_executed`." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "amountRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The amount actually received (or refunded), in this asset's smallest unit; `null` until a receipt confirms it." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "The number of decimals of this asset's smallest unit." }, "transferPayout": { "anyOf": [ { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "transactionHashes": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "Destination chain transactions, or the funding intent identifiers binding the provider-confirmed ledger payout." }, "quotedFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Withdrawal fee in destination-asset units from the bound signed quote, or null when not disclosed. Actual received amount is recorded separately." } }, "required": [ "rail", "network", "address", "transactionHashes", "quotedFeeRaw" ] }, { "type": "null" } ], "description": "Where the payout landed and its transaction ids; `null` before settlement or for older withdrawals." }, "refundReason": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" }, { "type": "null" } ], "description": "When the step was refunded, 1Click's own code for why, such as `NO_LIQUIDITY` or `AMOUNT_LESS_THAN_MIN_AMOUNT_OUT`; `null` when it gave none, for any other step, and for a step refunded before Fin kept this. Show it, don't branch on it: 1Click may add codes." }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this transfer's outcome was observed." } }, "required": [ "id", "index", "state", "assetId", "amountRaw", "decimals", "transferPayout", "refundReason", "observedAt" ] }, "description": "The transfer the withdrawal made and what it received, as evidence." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What the debit (`debit.amountRaw`) was worth when the withdrawal ran, at the trusted price Fin checked its plan against. `null` before it has a plan, and when no price was recorded." } }, "required": [ "id", "terms", "debit", "status", "failureReason", "result", "createdAt", "startedAt", "reportedAt", "receipts", "value" ], "examples": [ { "id": "6e15459a-6fb6-4320-85d8-a320d9e65737", "terms": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000", "destination": { "rail": "chain", "network": "eth", "assetId": "asset_2222222222222222222222222222222222222222222222222222222222222222", "address": "0x2222222222222222222222222222222222222222" }, "minimumReceivedRaw": "975000", "maxFeeRaw": null, "maxValueLossBps": 250 }, "debit": { "assetId": "asset_1111111111111111111111111111111111111111111111111111111111111111", "amountRaw": "1000000" }, "status": "pending", "failureReason": null, "result": null, "createdAt": "2026-09-22T18:00:00.000Z", "startedAt": null, "reportedAt": null, "receipts": [], "value": null } ], "description": "A withdrawal from the agent wallet: its terms, its `status`, and the evidence behind it." }, "WithdrawalTerms": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to withdraw from the agent wallet: an `assetId` from Get balances." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The amount to withdraw, in the asset's smallest unit." }, "destination": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the recipient receives: an `id` from List supported assets." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." } }, "required": [ "rail", "network", "assetId", "address" ], "description": "Where the funds go: the network, the asset received and the recipient's address." }, "minimumReceivedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the recipient receives, in the received asset's smallest unit." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "The most the withdrawal fee can be, in the received asset's smallest unit. `null` when the provider does not state this fee separately, which does not mean zero; the minimum received and the loss limit still apply." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "assetId", "amountRaw", "destination", "minimumReceivedRaw", "maxFeeRaw", "maxValueLossBps" ], "description": "The exact terms of a withdrawal: what leaves the agent wallet, where it goes, and the limits it must stay within." }, "DepositTerms": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset to deposit: an `id` from List supported assets." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount the user sends, in the asset's smallest unit." }, "refundAddress": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Where the funds go back to if the deposit cannot be credited: an address the user controls on the network they send from." }, "minimumCreditRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least the agent wallet must be credited, in the same asset's smallest unit." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 300, "description": "The most the transfer may lose in total, fees and price movement included, in basis points (100 = 1%), from 1 to 300." } }, "required": [ "rail", "network", "assetId", "amountRaw", "refundAddress", "minimumCreditRaw", "maxValueLossBps" ], "description": "The exact terms of a deposit: what the user sends, from which network, and the limits the credit must stay within." }, "DepositAddress": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` it was created with." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The network the user sends on." }, "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset the user sends: an `id` from List supported assets." }, "state": { "type": "string", "enum": [ "preparing", "awaiting_deposit", "incomplete", "processing", "credited", "refunded", "unknown", "expired", "failed" ], "description": "Where the deposit is: `preparing` (getting the address), `awaiting_deposit` (waiting for the user's transfer), `processing`, then `credited` or `refunded`. `incomplete` means less than `minimumDepositRaw` arrived: it is refunded to the agent wallet, so tell the user not to top it up. `failed` means no address was issued. `expired` means the address stopped taking deposits with no transfer seen; a late transfer still moves it on. `unknown` means Fin saw something it could not confirm; it never proves that no money moved, so keep checking." }, "instruction": { "anyOf": [ { "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "Opaque stable Fin asset identity returned by balances and the transfer catalog." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "The asset's native blockchain network." }, "kind": { "type": "string", "enum": [ "native", "token" ], "description": "Native currency or a token contract according to the provider catalog." }, "contractAddress": { "anyOf": [ { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, { "type": "null" } ], "description": "Native-chain token identifier; null for native currency." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "Atomic-unit precision." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Display label; the asset id determines identity." } }, "required": [ "id", "network", "kind", "contractAddress", "decimals", "symbol" ], "description": "The asset to send, on its network, and the precision its amounts are in." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "The one-time address to send to. It takes one transfer: never save or reuse it." }, "memo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[\\x20-\\x7e]+$" }, { "type": "null" } ], "description": "Required deposit memo or tag, exactly as returned; null means absent." }, "minimumDepositRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The least one transfer must carry to be credited, in the asset's smallest unit. Less is refunded to the agent wallet." }, "sendBefore": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "Send by this time; a transfer sent later may be refunded instead of credited." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the address stops taking deposits. A transfer that arrives later is still watched, and refunded to the agent wallet." }, "creditEstimateSeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 86400 }, { "type": "null" } ], "description": "About how long the credit takes once the network has confirmed the transfer, in seconds; null when no estimate was given." } }, "required": [ "asset", "address", "memo", "minimumDepositRaw", "sendBefore", "expiresAt", "creditEstimateSeconds" ] }, { "type": "null" } ], "description": "Where and what to send; `null` until the address is issued." }, "receipt": { "anyOf": [ { "type": "object", "properties": { "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the outcome was observed." }, "state": { "type": "string", "enum": [ "credited", "refunded" ], "description": "Whether the transfer was credited or refunded." }, "depositedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What arrived at the address." }, "creditedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the agent wallet was credited; zero when all of it was refunded." }, "refundedRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What went back to the agent wallet uncredited, such as a transfer below the minimum." }, "sourceTransactionHashes": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The transfers that paid the address, on the network they were sent on." }, "refundTransactionHashes": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Network transaction or ledger intent identifier; opaque and case-sensitive, not necessarily an EVM hash." }, "description": "The refund's ledger identifiers, when they were reported." } }, "required": [ "observedAt", "state", "depositedRaw", "creditedRaw", "refundedRaw", "sourceTransactionHashes", "refundTransactionHashes" ] }, { "type": "null" } ], "description": "What arrived, what was credited and what was refunded; `null` until then." }, "seenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When Fin first saw the user's transfer: the first check that found it on its way, or already credited or refunded. `null` until then, and for a transfer Fin saw before it kept this." }, "arrivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "What 1Click reported arriving while it confirmed the transfer, in the asset's smallest unit; `null` until it reports a figure. For display while it confirms: `receipt` records what was finally credited." }, "value": { "anyOf": [ { "$ref": "#/components/schemas/ValueAtTime" }, { "type": "null" } ], "description": "What was credited (`receipt.creditedRaw`) was worth when it was credited, at the price Fin recorded with the credit. `null` until it is credited, and when no fresh price was known then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the deposit address was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed." } }, "required": [ "id", "requestKey", "network", "assetId", "state", "instruction", "receipt", "seenAt", "arrivedRaw", "value", "createdAt", "updatedAt" ], "description": "A one-time address that takes one transfer of any amount into the agent wallet, and how that transfer is going." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "SolanaFundInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to move from the agent wallet into the agent's Solana account as SOL, in six-decimal atomic units: 5 USDC is \"5000000\". Spent from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." }, "payWith": { "description": "Approved in chat as one call: the coin this funding pays with instead of a USDC or USDT holding, and the most of it it may spend. Never SOL.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "Move an exact amount of USDC or USDT, or that many dollars of a coin, from the agent wallet into its own Solana account as SOL." }, "SolanaWithdrawInput": { "type": "object", "properties": { "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Withdraw an exact amount of SOL." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to withdraw, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Withdraw an exact amount of SOL." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_spendable", "description": "Withdraw all the SOL above the reserve the account keeps for rent and network fees." } }, "required": [ "kind" ], "description": "Withdraw all the spendable SOL." } ], "description": "How much SOL to withdraw from the agent's Solana account." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns it to the agent wallet as USDC on NEAR; `sol` returns it to the agent wallet as SOL." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees: at most 300. Required; no default." } }, "required": [ "amount", "receive", "maxValueLossBps" ], "description": "Move SOL from the agent's own Solana account back to its agent wallet." }, "SolanaSellManyInput": { "type": "object", "properties": { "sells": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/SolanaSale" }, "description": "The coins to sell, in the order they are sold: 2 to 6, each a different mint, none of them SOL itself." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the summed proceeds of every sale that went through to the agent wallet as USDC on NEAR, in one transfer once the last sale ran; `sol` keeps them as SOL in the agent's Solana account." } }, "required": [ "sells", "receive" ], "description": "Several sells of Solana tokens held in the agent's own Solana account, approved together and run as one: each sale on its own, one after another, then one transfer of what they returned." }, "SolanaSale": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "maxValueLossBps" ], "description": "One coin of a multi-coin sale, sold through the agent's own Solana account." }, "SolanaTrade": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id, for Get a Solana trade." }, "requestKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The `Idempotency-Key` it was placed under." }, "trade": { "description": "The trade as the user signed it.", "$ref": "#/components/schemas/SolanaTradeRequest" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "partial", "refunded", "failed", "denied", "expired", "uncertain" ], "description": "`pending` until it starts, usually while it waits for the user's approval. `processing` while it runs, or while a Solana transaction it sent, or its transfer back to the agent wallet, has not finished. Then `completed` (the tokens bought, the proceeds of a sale or the SOL moved arrived), `partial` (part of it stands: a buy whose swap never happened after the account was funded, so the SOL is in the agent's Solana account, or a sale whose swap landed but whose transfer back did not finish, or that kept SOL, so the SOL is in the account or with 1Click until it refunds it; `solLeftLamports` says how much the account holds), `refunded` (1Click sent the funds back where they came from) or `failed` (nothing moved; `failureReason` says why). `denied` and `expired` mean the user denied it, or its approval ran out, before it started. `uncertain` means the result could not be confirmed yet: never ask the agent for a replacement, keep checking. `completed`, `partial`, `refunded`, `failed`, `denied` and `expired` are final." }, "failureReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_funds", "quote_rejected", "quote_expired", "unavailable", "not_authorized", "stopped", "not_executed", "signing_disabled" ] }, { "type": "null" } ], "description": "When `status` is `failed`, why; otherwise `null`. `insufficient_funds`: the agent wallet or the Solana account did not hold enough, the account's reserve included. `quote_rejected`: the price or the route failed its checks, the loss limit would have been crossed, or a buy was under the minimum. `unavailable`: a temporary problem stopped it before anything was sent. `not_authorized`: the approval no longer covered it, or the token is one the agent does not trade. `stopped`: an operator paused trading or turned the wallet off. `not_executed`: nothing it sent landed before it expired. `signing_disabled`: this deployment does not sign trades. In every case nothing moved." }, "stage": { "description": "The step it is on, once it started: `funding` moves USDC from the agent wallet to the Solana account as SOL through 1Click, `swap` trades on Jupiter, `sweep` sends a sale's SOL back to the agent wallet. A higher `revision` is newer.", "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1, "maximum": 1024, "description": "Persisted lifecycle stage number. Ignore an older snapshot for the same operation." }, "phase": { "type": "string", "enum": [ "funding", "swap", "sweep" ] }, "state": { "type": "string", "enum": [ "preparing", "prepared", "submitting", "pending", "delivering", "confirmed", "uncertain", "refunded", "failed", "not_executed" ] }, "transactionIndex": { "description": "The stored native transaction attempt, never a funding plan leg index.", "type": "integer", "minimum": 0, "maximum": 5 } }, "required": [ "revision", "phase", "state" ] }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "completeBy": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest it may still run, as the user signed it; its status is final by then." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was placed." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When its records last changed." } }, "required": [ "id", "requestKey", "trade", "status", "failureReason", "transactions", "completeBy", "createdAt", "updatedAt" ], "description": "A Solana buy or sale the user placed themselves: its status, the step it is on, and what it paid and received." }, "SolanaTradeRequest": { "oneOf": [ { "type": "object", "properties": { "side": { "type": "string", "const": "buy", "description": "Buy the token." }, "buy": { "description": "The exact buy: the token, what it pays, its all-in loss bound and its SOL top-up cap.", "$ref": "#/components/schemas/SolanaBuyInput" } }, "required": [ "side", "buy" ] }, { "type": "object", "properties": { "side": { "type": "string", "const": "sell", "description": "Sell the token." }, "sell": { "description": "The exact sale: the token, how much of it, where the proceeds go and its all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" } }, "required": [ "side", "sell" ] } ], "description": "A buy or a sale of one Solana token through the agent's own Solana account." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List notifications 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. `GET /v1/users/{userId}/notifications` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "How many notifications to return, at most 50." }, { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "The `nextCursor` from the previous page; omit for the newest notifications." }, { "schema": { "type": "string" }, "in": "query", "name": "unread", "required": false, "description": "Only unread notifications when true." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "conversationId", "required": false, "description": "Only notifications about this conversation: its approvals, questions and replies." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/notifications' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 A page of notifications, and how many are unread. ```json { "description": "A page of notifications, and how many are unread.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The notification's id." }, "kind": { "type": "string", "enum": [ "approval", "question", "automation_report", "trade", "order_filled", "deposit", "withdrawal", "automation_attention", "reply", "holding_move", "market_story", "weekly_look" ], "description": "What happened: an `approval` or `question` waiting for the user, an `automation_report`, a `trade` that ended (one an automation made, one the agent made in chat, the user's own swap, or a Solana buy or sale, the user's own on the token's page included), an `order_filled` (a limit order or a Polymarket order), a `deposit`, a `withdrawal`, an `automation_attention` problem with an automation, fin's `reply` in a chat the user left, or one of fin's own notices about what it noticed: a `holding_move` (a coin that is a real part of the user's money fell far more than it usually does, or their whole money fell 5% in a day), a `market_story` (big news about a coin they hold) or a `weekly_look` (fin's look at their week). Fin may add kinds: show one you do not know by its `title` and `body`." }, "category": { "type": "string", "enum": [ "needs_you", "alerts_and_reports", "money_moved", "automation_problems", "replies", "big_news", "big_moves", "weekly_look" ], "description": "Which of the user's notification settings it falls under, if your app lets them choose: `needs_you`, `alerts_and_reports`, `money_moved`, `automation_problems`, `replies`, or, for fin's own notices, `big_news`, `big_moves` and `weekly_look`. Fin's notices are new to the user: leave their push off until the user turns it on." }, "tone": { "type": "string", "enum": [ "needs_you", "problem", "resolved", "neutral" ], "description": "How it reads, to tint its icon: `needs_you` while an approval or a question waits for the user, when fin paused an automation until its owner acts, or when an automation's approval ends in three days; `problem` when something went wrong (a trade or a withdrawal that didn't go through, a refunded deposit, an automation that can't check its data or run, a reply that failed) or fin noticed a fall in the user's money; `resolved` when an automation's problem is over; `neutral` otherwise." }, "title": { "type": "string", "description": "The title to show, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." }, "withoutAmounts": { "type": "object", "properties": { "title": { "type": "string", "description": "The notification's title, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." } }, "required": [ "title", "body" ], "description": "The same notification without amounts, for a lock screen or anywhere the user asked you not to show them." }, "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "An approval waiting for the user.", "enum": [ "approval" ] }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the approval is in." } }, "required": [ "type", "approvalId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A question fin asked the user.", "enum": [ "question" ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The question's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the question is in." } }, "required": [ "type", "questionId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A run an automation started.", "enum": [ "automation_run" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id, as Get an automation run takes it." } }, "required": [ "type", "automationId", "automationRunId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A trade the agent made.", "enum": [ "trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id, as Get a trade takes it." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A swap the user made in the agent wallet.", "enum": [ "swap" ] }, "swapId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id, as Get a swap takes it." } }, "required": [ "type", "swapId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A buy or a sale of a Solana token, by the user on its page or by the agent.", "enum": [ "solana_trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "For a trade the user placed on the token's page, its id as Get a Solana trade takes it; for one the agent made, the id of its `solana` item in List activity." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A Polymarket order.", "enum": [ "prediction_order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a prediction order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A limit order.", "enum": [ "order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a limit order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A deposit into the agent wallet.", "enum": [ "deposit" ] }, "depositId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id, as Get a deposit takes it." } }, "required": [ "type", "depositId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A transfer to a deposit address.", "enum": [ "deposit_address" ] }, "depositAddressId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id, as Get a deposit address takes it." } }, "required": [ "type", "depositAddressId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A withdrawal from the agent wallet.", "enum": [ "withdrawal" ] }, "withdrawalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id, as Get a withdrawal takes it." } }, "required": [ "type", "withdrawalId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "An automation as a whole.", "enum": [ "automation" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." } }, "required": [ "type", "automationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "fin's reply in a conversation.", "enum": [ "conversation" ] }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run that replied." } }, "required": [ "type", "conversationId", "runId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A market story fin's news desk is carrying.", "enum": [ "story" ] }, "storyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The story's id, as Get a market story takes it." } }, "required": [ "type", "storyId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A coin or token the user holds.", "enum": [ "asset" ] }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEAR Intents asset id, or `solana:` for a Solana token." } }, "required": [ "type", "assetId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The user's money over one week, as fin looked at it.", "enum": [ "week" ] }, "weekOf": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The Monday the week began, as an ISO date." } }, "required": [ "type", "weekOf" ] } ], "description": "What the notification is about. Open its page when the user opens the notification." }, "tokenId": { "description": "The token the notification is about, to draw its icon beside the text: what a trade or order bought (or sold, when it received dollars), or what a deposit brought or a withdrawal sent. A NEAR Intents asset id, or `solana:` for a Solana token. Absent for the other kinds, and when Fin cannot name the token.", "type": "string", "minLength": 1, "maxLength": 256 }, "status": { "description": "For an approval or a question: `waiting` while the user can still answer, `expired` once it ran out, `done` once it was answered. `waiting` also marks an `automation_attention` for an automation fin paused until its owner acts, which has no `expiresAt` and reads `done` once they have. Absent otherwise.", "type": "string", "enum": [ "waiting", "expired", "done" ] }, "action": { "description": "On an automation fin paused for its owner (`status` `waiting`), what moves it on: `add_funds` or `edit_automation`. Absent when the owner moves it on from the automation's page, by a choice or by resuming it, and on every other notification.", "type": "string", "enum": [ "add_funds", "edit_automation" ] }, "expiresAt": { "description": "For an approval or a question that is waiting: when it runs out.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "options": { "description": "Ways to act on one of fin's own notices (`holding_move`, `market_story`, `weekly_look`), best first. Show them where the user opens the notification, never in a push or on a lock screen, under a line saying they are options, not recommendations, and that doing nothing is fine. Absent on every other notification.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/NotificationOption" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened." }, "readAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user read it, or when its approval or question was answered or ran out; null while unread." } }, "required": [ "id", "kind", "category", "tone", "title", "body", "withoutAmounts", "subject", "createdAt", "readAt" ] }, "description": "This page of notifications, newest first." }, "nextCursor": { "description": "Pass it back as `cursor` for older notifications; null at the end.", "type": [ "string", "null" ] }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many of the user's notifications are unread, for a badge." } }, "required": [ "data", "nextCursor", "unreadCount" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "notifications.list", "summary": "List notifications", "tags": [ "notifications" ], "description": "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.", "parameters": [ { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "in": "query", "name": "limit", "required": false, "description": "How many notifications to return, at most 50." }, { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "The `nextCursor` from the previous page; omit for the newest notifications." }, { "schema": { "type": "string" }, "in": "query", "name": "unread", "required": false, "description": "Only unread notifications when true." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "conversationId", "required": false, "description": "Only notifications about this conversation: its approvals, questions and replies." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "A page of notifications, and how many are unread.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The notification's id." }, "kind": { "type": "string", "enum": [ "approval", "question", "automation_report", "trade", "order_filled", "deposit", "withdrawal", "automation_attention", "reply", "holding_move", "market_story", "weekly_look" ], "description": "What happened: an `approval` or `question` waiting for the user, an `automation_report`, a `trade` that ended (one an automation made, one the agent made in chat, the user's own swap, or a Solana buy or sale, the user's own on the token's page included), an `order_filled` (a limit order or a Polymarket order), a `deposit`, a `withdrawal`, an `automation_attention` problem with an automation, fin's `reply` in a chat the user left, or one of fin's own notices about what it noticed: a `holding_move` (a coin that is a real part of the user's money fell far more than it usually does, or their whole money fell 5% in a day), a `market_story` (big news about a coin they hold) or a `weekly_look` (fin's look at their week). Fin may add kinds: show one you do not know by its `title` and `body`." }, "category": { "type": "string", "enum": [ "needs_you", "alerts_and_reports", "money_moved", "automation_problems", "replies", "big_news", "big_moves", "weekly_look" ], "description": "Which of the user's notification settings it falls under, if your app lets them choose: `needs_you`, `alerts_and_reports`, `money_moved`, `automation_problems`, `replies`, or, for fin's own notices, `big_news`, `big_moves` and `weekly_look`. Fin's notices are new to the user: leave their push off until the user turns it on." }, "tone": { "type": "string", "enum": [ "needs_you", "problem", "resolved", "neutral" ], "description": "How it reads, to tint its icon: `needs_you` while an approval or a question waits for the user, when fin paused an automation until its owner acts, or when an automation's approval ends in three days; `problem` when something went wrong (a trade or a withdrawal that didn't go through, a refunded deposit, an automation that can't check its data or run, a reply that failed) or fin noticed a fall in the user's money; `resolved` when an automation's problem is over; `neutral` otherwise." }, "title": { "type": "string", "description": "The title to show, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." }, "withoutAmounts": { "type": "object", "properties": { "title": { "type": "string", "description": "The notification's title, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." } }, "required": [ "title", "body" ], "description": "The same notification without amounts, for a lock screen or anywhere the user asked you not to show them." }, "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "An approval waiting for the user.", "enum": [ "approval" ] }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the approval is in." } }, "required": [ "type", "approvalId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A question fin asked the user.", "enum": [ "question" ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The question's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the question is in." } }, "required": [ "type", "questionId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A run an automation started.", "enum": [ "automation_run" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id, as Get an automation run takes it." } }, "required": [ "type", "automationId", "automationRunId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A trade the agent made.", "enum": [ "trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id, as Get a trade takes it." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A swap the user made in the agent wallet.", "enum": [ "swap" ] }, "swapId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id, as Get a swap takes it." } }, "required": [ "type", "swapId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A buy or a sale of a Solana token, by the user on its page or by the agent.", "enum": [ "solana_trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "For a trade the user placed on the token's page, its id as Get a Solana trade takes it; for one the agent made, the id of its `solana` item in List activity." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A Polymarket order.", "enum": [ "prediction_order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a prediction order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A limit order.", "enum": [ "order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a limit order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A deposit into the agent wallet.", "enum": [ "deposit" ] }, "depositId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id, as Get a deposit takes it." } }, "required": [ "type", "depositId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A transfer to a deposit address.", "enum": [ "deposit_address" ] }, "depositAddressId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id, as Get a deposit address takes it." } }, "required": [ "type", "depositAddressId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A withdrawal from the agent wallet.", "enum": [ "withdrawal" ] }, "withdrawalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id, as Get a withdrawal takes it." } }, "required": [ "type", "withdrawalId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "An automation as a whole.", "enum": [ "automation" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." } }, "required": [ "type", "automationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "fin's reply in a conversation.", "enum": [ "conversation" ] }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run that replied." } }, "required": [ "type", "conversationId", "runId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A market story fin's news desk is carrying.", "enum": [ "story" ] }, "storyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The story's id, as Get a market story takes it." } }, "required": [ "type", "storyId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A coin or token the user holds.", "enum": [ "asset" ] }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEAR Intents asset id, or `solana:` for a Solana token." } }, "required": [ "type", "assetId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The user's money over one week, as fin looked at it.", "enum": [ "week" ] }, "weekOf": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The Monday the week began, as an ISO date." } }, "required": [ "type", "weekOf" ] } ], "description": "What the notification is about. Open its page when the user opens the notification." }, "tokenId": { "description": "The token the notification is about, to draw its icon beside the text: what a trade or order bought (or sold, when it received dollars), or what a deposit brought or a withdrawal sent. A NEAR Intents asset id, or `solana:` for a Solana token. Absent for the other kinds, and when Fin cannot name the token.", "type": "string", "minLength": 1, "maxLength": 256 }, "status": { "description": "For an approval or a question: `waiting` while the user can still answer, `expired` once it ran out, `done` once it was answered. `waiting` also marks an `automation_attention` for an automation fin paused until its owner acts, which has no `expiresAt` and reads `done` once they have. Absent otherwise.", "type": "string", "enum": [ "waiting", "expired", "done" ] }, "action": { "description": "On an automation fin paused for its owner (`status` `waiting`), what moves it on: `add_funds` or `edit_automation`. Absent when the owner moves it on from the automation's page, by a choice or by resuming it, and on every other notification.", "type": "string", "enum": [ "add_funds", "edit_automation" ] }, "expiresAt": { "description": "For an approval or a question that is waiting: when it runs out.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "options": { "description": "Ways to act on one of fin's own notices (`holding_move`, `market_story`, `weekly_look`), best first. Show them where the user opens the notification, never in a push or on a lock screen, under a line saying they are options, not recommendations, and that doing nothing is fine. Absent on every other notification.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/NotificationOption" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened." }, "readAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user read it, or when its approval or question was answered or ran out; null while unread." } }, "required": [ "id", "kind", "category", "tone", "title", "body", "withoutAmounts", "subject", "createdAt", "readAt" ] }, "description": "This page of notifications, newest first." }, "nextCursor": { "description": "Pass it back as `cursor` for older notifications; null at the end.", "type": [ "string", "null" ] }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many of the user's notifications are unread, for a badge." } }, "required": [ "data", "nextCursor", "unreadCount" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "NotificationOption": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The option, verb first: `Protect the rest`." }, "detail": { "type": "string", "minLength": 1, "maxLength": 140, "description": "Its terms in one line: `Sell only if it falls another 5%, to $1,696.`" }, "button": { "type": "string", "minLength": 1, "maxLength": 24, "description": "Its button's label: `Set it`." }, "review": { "oneOf": [ { "$ref": "#/components/schemas/AskReview" }, { "$ref": "#/components/schemas/OpenReview" } ], "description": "What choosing it does: `ask` opens fin's chat with `question` as the user's message, and fin proposes and waits for the user's approval as always; `open` opens a product's own form, filled in (`targetId` `earn`: Earn, with the amount to put in)." } }, "required": [ "title", "detail", "button", "review" ], "description": "One way to act on one of fin's notices. It only opens fin's chat or a form: nothing moves until the user approves it." }, "AskReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "ask", "description": "Which review this is." }, "question": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The question the chat opens with." } }, "required": [ "kind", "question" ], "description": "Ask Fin: opens the page's chat with the question." }, "OpenReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Which review this is." }, "targetId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Your app's id for the form." }, "amount": { "description": "What Fin fills in.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "kind", "targetId" ], "description": "A product Fin cannot run for you: its own form, filled in. Fin does not suggest it yet." }, "AssetAmount": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/ReviewAsset" }, "amountRaw": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "In the asset's smallest unit, as a decimal integer string: `3000000` is 3 USDC." } }, "required": [ "asset", "amountRaw" ], "description": "An exact amount of one asset." }, "ReviewAsset": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset as Get balances and Prepare an order name it." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 32, "description": "The asset's symbol: `NEAR`, `USDC`, `BTC`, `AAPL`." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36, "description": "The asset's own scale: 24 for NEAR, 6 for USDC, 8 for BTC." }, "network": { "description": "The chain it sits on, for its badge: `near`, `base`; omitted for none.", "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" } }, "required": [ "assetId", "symbol", "decimals" ], "description": "An asset a review names, as it draws and prints it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Mark notifications read 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. `POST /v1/users/{userId}/notifications/read` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "notificationIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The notifications to mark read, at most 100." } }, "required": [ "notificationIds" ], "additionalProperties": false }, { "type": "object", "properties": { "through": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Mark this notification and every older one read: send the newest one the user saw, so one that arrived since stays unread." } }, "required": [ "through" ], "additionalProperties": false } ] } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/notifications/read' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The notifications this call marked read, and how many are unread now. ```json { "description": "The notifications this call marked read, and how many are unread now.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The notification's id." }, "kind": { "type": "string", "enum": [ "approval", "question", "automation_report", "trade", "order_filled", "deposit", "withdrawal", "automation_attention", "reply", "holding_move", "market_story", "weekly_look" ], "description": "What happened: an `approval` or `question` waiting for the user, an `automation_report`, a `trade` that ended (one an automation made, one the agent made in chat, the user's own swap, or a Solana buy or sale, the user's own on the token's page included), an `order_filled` (a limit order or a Polymarket order), a `deposit`, a `withdrawal`, an `automation_attention` problem with an automation, fin's `reply` in a chat the user left, or one of fin's own notices about what it noticed: a `holding_move` (a coin that is a real part of the user's money fell far more than it usually does, or their whole money fell 5% in a day), a `market_story` (big news about a coin they hold) or a `weekly_look` (fin's look at their week). Fin may add kinds: show one you do not know by its `title` and `body`." }, "category": { "type": "string", "enum": [ "needs_you", "alerts_and_reports", "money_moved", "automation_problems", "replies", "big_news", "big_moves", "weekly_look" ], "description": "Which of the user's notification settings it falls under, if your app lets them choose: `needs_you`, `alerts_and_reports`, `money_moved`, `automation_problems`, `replies`, or, for fin's own notices, `big_news`, `big_moves` and `weekly_look`. Fin's notices are new to the user: leave their push off until the user turns it on." }, "tone": { "type": "string", "enum": [ "needs_you", "problem", "resolved", "neutral" ], "description": "How it reads, to tint its icon: `needs_you` while an approval or a question waits for the user, when fin paused an automation until its owner acts, or when an automation's approval ends in three days; `problem` when something went wrong (a trade or a withdrawal that didn't go through, a refunded deposit, an automation that can't check its data or run, a reply that failed) or fin noticed a fall in the user's money; `resolved` when an automation's problem is over; `neutral` otherwise." }, "title": { "type": "string", "description": "The title to show, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." }, "withoutAmounts": { "type": "object", "properties": { "title": { "type": "string", "description": "The notification's title, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." } }, "required": [ "title", "body" ], "description": "The same notification without amounts, for a lock screen or anywhere the user asked you not to show them." }, "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "An approval waiting for the user.", "enum": [ "approval" ] }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the approval is in." } }, "required": [ "type", "approvalId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A question fin asked the user.", "enum": [ "question" ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The question's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the question is in." } }, "required": [ "type", "questionId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A run an automation started.", "enum": [ "automation_run" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id, as Get an automation run takes it." } }, "required": [ "type", "automationId", "automationRunId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A trade the agent made.", "enum": [ "trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id, as Get a trade takes it." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A swap the user made in the agent wallet.", "enum": [ "swap" ] }, "swapId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id, as Get a swap takes it." } }, "required": [ "type", "swapId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A buy or a sale of a Solana token, by the user on its page or by the agent.", "enum": [ "solana_trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "For a trade the user placed on the token's page, its id as Get a Solana trade takes it; for one the agent made, the id of its `solana` item in List activity." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A Polymarket order.", "enum": [ "prediction_order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a prediction order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A limit order.", "enum": [ "order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a limit order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A deposit into the agent wallet.", "enum": [ "deposit" ] }, "depositId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id, as Get a deposit takes it." } }, "required": [ "type", "depositId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A transfer to a deposit address.", "enum": [ "deposit_address" ] }, "depositAddressId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id, as Get a deposit address takes it." } }, "required": [ "type", "depositAddressId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A withdrawal from the agent wallet.", "enum": [ "withdrawal" ] }, "withdrawalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id, as Get a withdrawal takes it." } }, "required": [ "type", "withdrawalId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "An automation as a whole.", "enum": [ "automation" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." } }, "required": [ "type", "automationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "fin's reply in a conversation.", "enum": [ "conversation" ] }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run that replied." } }, "required": [ "type", "conversationId", "runId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A market story fin's news desk is carrying.", "enum": [ "story" ] }, "storyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The story's id, as Get a market story takes it." } }, "required": [ "type", "storyId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A coin or token the user holds.", "enum": [ "asset" ] }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEAR Intents asset id, or `solana:` for a Solana token." } }, "required": [ "type", "assetId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The user's money over one week, as fin looked at it.", "enum": [ "week" ] }, "weekOf": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The Monday the week began, as an ISO date." } }, "required": [ "type", "weekOf" ] } ], "description": "What the notification is about. Open its page when the user opens the notification." }, "tokenId": { "description": "The token the notification is about, to draw its icon beside the text: what a trade or order bought (or sold, when it received dollars), or what a deposit brought or a withdrawal sent. A NEAR Intents asset id, or `solana:` for a Solana token. Absent for the other kinds, and when Fin cannot name the token.", "type": "string", "minLength": 1, "maxLength": 256 }, "status": { "description": "For an approval or a question: `waiting` while the user can still answer, `expired` once it ran out, `done` once it was answered. `waiting` also marks an `automation_attention` for an automation fin paused until its owner acts, which has no `expiresAt` and reads `done` once they have. Absent otherwise.", "type": "string", "enum": [ "waiting", "expired", "done" ] }, "action": { "description": "On an automation fin paused for its owner (`status` `waiting`), what moves it on: `add_funds` or `edit_automation`. Absent when the owner moves it on from the automation's page, by a choice or by resuming it, and on every other notification.", "type": "string", "enum": [ "add_funds", "edit_automation" ] }, "expiresAt": { "description": "For an approval or a question that is waiting: when it runs out.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "options": { "description": "Ways to act on one of fin's own notices (`holding_move`, `market_story`, `weekly_look`), best first. Show them where the user opens the notification, never in a push or on a lock screen, under a line saying they are options, not recommendations, and that doing nothing is fine. Absent on every other notification.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/NotificationOption" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened." }, "readAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user read it, or when its approval or question was answered or ran out; null while unread." } }, "required": [ "id", "kind", "category", "tone", "title", "body", "withoutAmounts", "subject", "createdAt", "readAt" ] }, "description": "The newest notifications this call marked read, at most 100. A through request can mark more; refresh the inbox to read their current state." }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many are unread now." } }, "required": [ "data", "unreadCount" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "notifications.markRead", "summary": "Mark notifications read", "tags": [ "notifications" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "notificationIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "The notifications to mark read, at most 100." } }, "required": [ "notificationIds" ], "additionalProperties": false }, { "type": "object", "properties": { "through": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Mark this notification and every older one read: send the newest one the user saw, so one that arrived since stays unread." } }, "required": [ "through" ], "additionalProperties": false } ] } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The notifications this call marked read, and how many are unread now.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The notification's id." }, "kind": { "type": "string", "enum": [ "approval", "question", "automation_report", "trade", "order_filled", "deposit", "withdrawal", "automation_attention", "reply", "holding_move", "market_story", "weekly_look" ], "description": "What happened: an `approval` or `question` waiting for the user, an `automation_report`, a `trade` that ended (one an automation made, one the agent made in chat, the user's own swap, or a Solana buy or sale, the user's own on the token's page included), an `order_filled` (a limit order or a Polymarket order), a `deposit`, a `withdrawal`, an `automation_attention` problem with an automation, fin's `reply` in a chat the user left, or one of fin's own notices about what it noticed: a `holding_move` (a coin that is a real part of the user's money fell far more than it usually does, or their whole money fell 5% in a day), a `market_story` (big news about a coin they hold) or a `weekly_look` (fin's look at their week). Fin may add kinds: show one you do not know by its `title` and `body`." }, "category": { "type": "string", "enum": [ "needs_you", "alerts_and_reports", "money_moved", "automation_problems", "replies", "big_news", "big_moves", "weekly_look" ], "description": "Which of the user's notification settings it falls under, if your app lets them choose: `needs_you`, `alerts_and_reports`, `money_moved`, `automation_problems`, `replies`, or, for fin's own notices, `big_news`, `big_moves` and `weekly_look`. Fin's notices are new to the user: leave their push off until the user turns it on." }, "tone": { "type": "string", "enum": [ "needs_you", "problem", "resolved", "neutral" ], "description": "How it reads, to tint its icon: `needs_you` while an approval or a question waits for the user, when fin paused an automation until its owner acts, or when an automation's approval ends in three days; `problem` when something went wrong (a trade or a withdrawal that didn't go through, a refunded deposit, an automation that can't check its data or run, a reply that failed) or fin noticed a fall in the user's money; `resolved` when an automation's problem is over; `neutral` otherwise." }, "title": { "type": "string", "description": "The title to show, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." }, "withoutAmounts": { "type": "object", "properties": { "title": { "type": "string", "description": "The notification's title, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." } }, "required": [ "title", "body" ], "description": "The same notification without amounts, for a lock screen or anywhere the user asked you not to show them." }, "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "An approval waiting for the user.", "enum": [ "approval" ] }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the approval is in." } }, "required": [ "type", "approvalId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A question fin asked the user.", "enum": [ "question" ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The question's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the question is in." } }, "required": [ "type", "questionId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A run an automation started.", "enum": [ "automation_run" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id, as Get an automation run takes it." } }, "required": [ "type", "automationId", "automationRunId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A trade the agent made.", "enum": [ "trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id, as Get a trade takes it." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A swap the user made in the agent wallet.", "enum": [ "swap" ] }, "swapId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id, as Get a swap takes it." } }, "required": [ "type", "swapId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A buy or a sale of a Solana token, by the user on its page or by the agent.", "enum": [ "solana_trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "For a trade the user placed on the token's page, its id as Get a Solana trade takes it; for one the agent made, the id of its `solana` item in List activity." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A Polymarket order.", "enum": [ "prediction_order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a prediction order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A limit order.", "enum": [ "order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a limit order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A deposit into the agent wallet.", "enum": [ "deposit" ] }, "depositId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id, as Get a deposit takes it." } }, "required": [ "type", "depositId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A transfer to a deposit address.", "enum": [ "deposit_address" ] }, "depositAddressId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id, as Get a deposit address takes it." } }, "required": [ "type", "depositAddressId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A withdrawal from the agent wallet.", "enum": [ "withdrawal" ] }, "withdrawalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id, as Get a withdrawal takes it." } }, "required": [ "type", "withdrawalId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "An automation as a whole.", "enum": [ "automation" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." } }, "required": [ "type", "automationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "fin's reply in a conversation.", "enum": [ "conversation" ] }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run that replied." } }, "required": [ "type", "conversationId", "runId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A market story fin's news desk is carrying.", "enum": [ "story" ] }, "storyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The story's id, as Get a market story takes it." } }, "required": [ "type", "storyId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A coin or token the user holds.", "enum": [ "asset" ] }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEAR Intents asset id, or `solana:` for a Solana token." } }, "required": [ "type", "assetId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The user's money over one week, as fin looked at it.", "enum": [ "week" ] }, "weekOf": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The Monday the week began, as an ISO date." } }, "required": [ "type", "weekOf" ] } ], "description": "What the notification is about. Open its page when the user opens the notification." }, "tokenId": { "description": "The token the notification is about, to draw its icon beside the text: what a trade or order bought (or sold, when it received dollars), or what a deposit brought or a withdrawal sent. A NEAR Intents asset id, or `solana:` for a Solana token. Absent for the other kinds, and when Fin cannot name the token.", "type": "string", "minLength": 1, "maxLength": 256 }, "status": { "description": "For an approval or a question: `waiting` while the user can still answer, `expired` once it ran out, `done` once it was answered. `waiting` also marks an `automation_attention` for an automation fin paused until its owner acts, which has no `expiresAt` and reads `done` once they have. Absent otherwise.", "type": "string", "enum": [ "waiting", "expired", "done" ] }, "action": { "description": "On an automation fin paused for its owner (`status` `waiting`), what moves it on: `add_funds` or `edit_automation`. Absent when the owner moves it on from the automation's page, by a choice or by resuming it, and on every other notification.", "type": "string", "enum": [ "add_funds", "edit_automation" ] }, "expiresAt": { "description": "For an approval or a question that is waiting: when it runs out.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "options": { "description": "Ways to act on one of fin's own notices (`holding_move`, `market_story`, `weekly_look`), best first. Show them where the user opens the notification, never in a push or on a lock screen, under a line saying they are options, not recommendations, and that doing nothing is fine. Absent on every other notification.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/NotificationOption" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened." }, "readAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user read it, or when its approval or question was answered or ran out; null while unread." } }, "required": [ "id", "kind", "category", "tone", "title", "body", "withoutAmounts", "subject", "createdAt", "readAt" ] }, "description": "The newest notifications this call marked read, at most 100. A through request can mark more; refresh the inbox to read their current state." }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many are unread now." } }, "required": [ "data", "unreadCount" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "NotificationOption": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The option, verb first: `Protect the rest`." }, "detail": { "type": "string", "minLength": 1, "maxLength": 140, "description": "Its terms in one line: `Sell only if it falls another 5%, to $1,696.`" }, "button": { "type": "string", "minLength": 1, "maxLength": 24, "description": "Its button's label: `Set it`." }, "review": { "oneOf": [ { "$ref": "#/components/schemas/AskReview" }, { "$ref": "#/components/schemas/OpenReview" } ], "description": "What choosing it does: `ask` opens fin's chat with `question` as the user's message, and fin proposes and waits for the user's approval as always; `open` opens a product's own form, filled in (`targetId` `earn`: Earn, with the amount to put in)." } }, "required": [ "title", "detail", "button", "review" ], "description": "One way to act on one of fin's notices. It only opens fin's chat or a form: nothing moves until the user approves it." }, "AskReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "ask", "description": "Which review this is." }, "question": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The question the chat opens with." } }, "required": [ "kind", "question" ], "description": "Ask Fin: opens the page's chat with the question." }, "OpenReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Which review this is." }, "targetId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Your app's id for the form." }, "amount": { "description": "What Fin fills in.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "kind", "targetId" ], "description": "A product Fin cannot run for you: its own form, filled in. Fin does not suggest it yet." }, "AssetAmount": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/ReviewAsset" }, "amountRaw": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "In the asset's smallest unit, as a decimal integer string: `3000000` is 3 USDC." } }, "required": [ "asset", "amountRaw" ], "description": "An exact amount of one asset." }, "ReviewAsset": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset as Get balances and Prepare an order name it." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 32, "description": "The asset's symbol: `NEAR`, `USDC`, `BTC`, `AAPL`." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36, "description": "The asset's own scale: 24 for NEAR, 6 for USDC, 8 for BTC." }, "network": { "description": "The chain it sits on, for its badge: `near`, `base`; omitted for none.", "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" } }, "required": [ "assetId", "symbol", "decimals" ], "description": "An asset a review names, as it draws and prints it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get AI usage budget 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 /v1/users/{userId}/budget` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/budget' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The user's AI usage budget. ```json { "description": "The user's AI usage budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "budgets.get", "summary": "Get AI usage budget", "tags": [ "budgets" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's AI usage budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Budget": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "`true` while today and this month both have budget left and the budget is not frozen; while `false`, new runs are refused with `budget_exhausted`." }, "frozen": { "type": "boolean", "description": "`true` when an operator froze this user's budget: nothing is left to spend." }, "snapshots": { "type": "array", "items": { "type": "object", "properties": { "periodKind": { "type": "string", "enum": [ "day", "month" ], "description": "Which period this snapshot covers: `day` (the UTC calendar day) or `month` (the calendar month)." }, "capCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The limit for this period, in US cents, as a JSON integer." }, "reservedCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What running work has reserved against the limit, in US cents, as a JSON integer." }, "spentCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What is already spent this period, in US cents, as a JSON integer." } }, "required": [ "periodKind", "capCents", "reservedCents", "spentCents" ] }, "description": "Today and this month, each with its limit, spend and reservations. What is left is `capCents - spentCents - reservedCents`." } }, "required": [ "ok", "frozen", "snapshots" ], "description": "The user's AI usage budget for today and this month: the cost of running the agent, not money in the wallet." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get partner usage 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 /v1/partner/usage` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "enum": [ "day", "month" ] }, "in": "query", "name": "periodKind", "required": true, "description": "Original UTC budget period, day or calendar month." }, { "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "in": "query", "name": "periodStart", "required": true, "description": "UTC date. Month periods must start on the first day." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/partner/usage?periodKind=YOUR_PERIODKIND&periodStart=YOUR_PERIODSTART' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 Exact inference costs and a bounded export page. ```json { "description": "Exact inference costs and a bounded export page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerUsage" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "partner.usage", "summary": "Get partner usage", "tags": [ "partner" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "enum": [ "day", "month" ] }, "in": "query", "name": "periodKind", "required": true, "description": "Original UTC budget period, day or calendar month." }, { "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "in": "query", "name": "periodStart", "required": true, "description": "UTC date. Month periods must start on the first day." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Exact inference costs and a bounded export page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerUsage" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "PartnerUsage": { "type": "object", "properties": { "periodKind": { "type": "string", "enum": [ "day", "month" ], "description": "Original UTC budget period, day or calendar month." }, "periodStart": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "UTC period start date; month periods begin on day one." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "UTC database snapshot time for this page and totals; later pages may see newer settlements." }, "totals": { "type": "object", "properties": { "knownCostCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." }, "reservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Maximum cents retained for every unresolved invocation, including uncertain dispatch. Not known spend." }, "uncertainReservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Subset of reservedCents whose dispatch may have incurred a charge." }, "invocationCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact invocation count in this period, encoded as a decimal string." }, "unresolvedCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact count without a known final charge, encoded as a decimal string." } }, "required": [ "knownCostCents", "reservedCents", "uncertainReservedCents", "invocationCount", "unresolvedCount" ], "description": "Canonical aggregate inference usage for this partner and original period, including its users' runs, its own runs, suggestions and voice transcriptions." }, "suggestionTotals": { "description": "The portion of totals incurred by suggestion sets, which have no run or agent attribution. Emitted by current servers; older servers omit it.", "type": "object", "properties": { "knownCostCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." }, "reservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Maximum cents retained for every unresolved invocation, including uncertain dispatch. Not known spend." }, "uncertainReservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Subset of reservedCents whose dispatch may have incurred a charge." }, "invocationCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact invocation count in this period, encoded as a decimal string." }, "unresolvedCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact count without a known final charge, encoded as a decimal string." } }, "required": [ "knownCostCents", "reservedCents", "uncertainReservedCents", "invocationCount", "unresolvedCount" ] }, "voiceTotals": { "description": "The portion of totals incurred by voice transcriptions (Transcribe a recording), which have no run or agent attribution. Emitted by current servers; older servers omit it.", "type": "object", "properties": { "knownCostCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." }, "reservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Maximum cents retained for every unresolved invocation, including uncertain dispatch. Not known spend." }, "uncertainReservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Subset of reservedCents whose dispatch may have incurred a charge." }, "invocationCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact invocation count in this period, encoded as a decimal string." }, "unresolvedCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact count without a known final charge, encoded as a decimal string." } }, "required": [ "knownCostCents", "reservedCents", "uncertainReservedCents", "invocationCount", "unresolvedCount" ] }, "partnerRunTotals": { "description": "The portion of totals incurred by runs Fin makes for the partner itself, such as market briefs, which have no user or agent and are not in this page. Emitted by current servers; older servers omit it.", "type": "object", "properties": { "knownCostCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." }, "reservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Maximum cents retained for every unresolved invocation, including uncertain dispatch. Not known spend." }, "uncertainReservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Subset of reservedCents whose dispatch may have incurred a charge." }, "invocationCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact invocation count in this period, encoded as a decimal string." }, "unresolvedCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact count without a known final charge, encoded as a decimal string." } }, "required": [ "knownCostCents", "reservedCents", "uncertainReservedCents", "invocationCount", "unresolvedCount" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "invocationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Canonical model invocation UUID; export pagination advances by this identity." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Root run UUID; continuations retain this root attribution." }, "userId": { "type": "string", "description": "Your identifier for the user whose run incurred this usage." }, "agentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Persistent admitted agent identity owned by this user." }, "status": { "type": "string", "enum": [ "reserved", "dispatched", "uncertain", "settled", "released" ], "description": "Retained accounting state of this model invocation." }, "maximumCostCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." }, "actualCostCents": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." }, { "type": "null" } ], "description": "Known provider charge in integer USD cents; null is unknown, never zero." }, "reservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." }, "uncertain": { "type": "boolean", "description": "Whether dispatch may have incurred an unestablished charge." } }, "required": [ "invocationId", "runId", "userId", "agentId", "status", "maximumCostCents", "actualCostCents", "reservedCents", "uncertain" ] }, "description": "Bounded page of the model invocation facts of your users' runs. Suggestions, voice transcriptions and the partner's own runs are included in totals, suggestionTotals, voiceTotals and partnerRunTotals, not this page. No prompt, key or raw provider payload." }, "nextCursor": { "description": "Opaque continuation cursor; pass as cursor for the next page, or null at the end.", "type": [ "string", "null" ] } }, "required": [ "periodKind", "periodStart", "asOf", "totals", "data", "nextCursor" ], "description": "Owner-scoped inference usage and export. Uses each invocation's original UTC budget period, including continuations. Null actual cost is unknown, never zero. No financial trading balances or customer billing are represented." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # Get partner quotas 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. `GET /v1/partner/quotas` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/partner/quotas' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 Current configured limits and observed capacity. ```json { "description": "Current configured limits and observed capacity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerQuotas" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "partner.quotas", "summary": "Get partner quotas", "tags": [ "partner" ], "description": "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.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Current configured limits and observed capacity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerQuotas" } } } }, "400": { "$ref": "#/components/responses/InvalidInputForRegistration" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [] }, "components": { "schemas": { "PartnerQuotas": { "type": "object", "properties": { "limits": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Authenticated requests permitted in one fixed database-clock UTC minute." }, "activeRuns": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Running root-run ceiling or current count; durable pauses release active capacity." }, "activeStreams": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unexpired partner stream lease ceiling or current count." }, "userStreams": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Concurrent stream limit for one user within the partner ceiling." }, "dayCapCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." }, "monthCapCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." } }, "required": [ "requestsPerMinute", "activeRuns", "activeStreams", "userStreams", "dayCapCents", "monthCapCents" ], "description": "Configured partner admission ceilings across all keys and replicas." }, "current": { "type": "object", "properties": { "activeRuns": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Running root-run ceiling or current count; durable pauses release active capacity." }, "activeStreams": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unexpired partner stream lease ceiling or current count." }, "requestsUsed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Accepted authenticated requests in the current fixed minute." } }, "required": [ "activeRuns", "activeStreams", "requestsUsed" ], "description": "Current shared utilization; observations do not reserve capacity." }, "periods": { "type": "array", "items": { "type": "object", "properties": { "knownCostCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact nonnegative USD integer cents; never a floating-point amount." }, "reservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Maximum cents retained for every unresolved invocation, including uncertain dispatch. Not known spend." }, "uncertainReservedCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Subset of reservedCents whose dispatch may have incurred a charge." }, "invocationCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact invocation count in this period, encoded as a decimal string." }, "unresolvedCount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Exact count without a known final charge, encoded as a decimal string." }, "periodKind": { "type": "string", "enum": [ "day", "month" ], "description": "Original UTC budget period, day or calendar month." }, "periodStart": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "UTC period start date; month periods begin on day one." }, "capCents": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Effective cap for this UTC period, including any audited operator adjustment." } }, "required": [ "knownCostCents", "reservedCents", "uncertainReservedCents", "invocationCount", "unresolvedCount", "periodKind", "periodStart", "capCents" ] }, "description": "Current day and month effective caps with canonical usage totals." }, "streamLeaseSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Shared stream lease lifetime; replicas renew or close before losing ownership." } }, "required": [ "limits", "current", "periods", "streamLeaseSeconds" ], "description": "Shared partner limits aggregate every key, user and API replica. Period caps include any audited operator adjustments; configured limits otherwise take effect when a period opens. Values are instantaneous observations, not a capacity reservation." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInputForRegistration": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # List partner features 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. `GET /v1/partner/features` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/partner/features' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 Every partner feature and whether your key has it. ```json { "description": "Every partner feature and whether your key has it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerFeatures" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "partner.features", "summary": "List partner features", "tags": [ "partner" ], "description": "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.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Every partner feature and whether your key has it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerFeatures" } } } }, "400": { "$ref": "#/components/responses/InvalidInputForRegistration" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [] }, "components": { "schemas": { "PartnerFeatures": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerFeature" }, "description": "Every feature, each once." } }, "required": [ "data" ], "description": "The features an operator turns on or off for each partner's key, and yours." }, "PartnerFeature": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "market_briefs", "disable_invite_code_requirements" ], "description": "The feature:\n- `market_briefs`: The partner-only market briefs API: what part of the market did and why, with sources.\n- `disable_invite_code_requirements`: Anyone can open an account in the partner's app without an invite code. An invite someone holds still shows and still gives its gift." }, "enabled": { "type": "boolean", "description": "Whether your key has the feature now." } }, "required": [ "feature", "enabled" ], "description": "A feature and whether your key has it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInputForRegistration": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # List notifications to deliver 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. `GET /v1/partner/notifications` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "after", "required": false, "description": "The `nextCursor` from your previous call; omit to start from the beginning." }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false, "description": "How many notifications to return, at most 500." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/partner/notifications' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 Your users' notifications after your cursor, and where this page ended. ```json { "description": "Your users' notifications after your cursor, and where this page ended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The notification's id." }, "kind": { "type": "string", "enum": [ "approval", "question", "automation_report", "trade", "order_filled", "deposit", "withdrawal", "automation_attention", "reply", "holding_move", "market_story", "weekly_look" ], "description": "What happened: an `approval` or `question` waiting for the user, an `automation_report`, a `trade` that ended (one an automation made, one the agent made in chat, the user's own swap, or a Solana buy or sale, the user's own on the token's page included), an `order_filled` (a limit order or a Polymarket order), a `deposit`, a `withdrawal`, an `automation_attention` problem with an automation, fin's `reply` in a chat the user left, or one of fin's own notices about what it noticed: a `holding_move` (a coin that is a real part of the user's money fell far more than it usually does, or their whole money fell 5% in a day), a `market_story` (big news about a coin they hold) or a `weekly_look` (fin's look at their week). Fin may add kinds: show one you do not know by its `title` and `body`." }, "category": { "type": "string", "enum": [ "needs_you", "alerts_and_reports", "money_moved", "automation_problems", "replies", "big_news", "big_moves", "weekly_look" ], "description": "Which of the user's notification settings it falls under, if your app lets them choose: `needs_you`, `alerts_and_reports`, `money_moved`, `automation_problems`, `replies`, or, for fin's own notices, `big_news`, `big_moves` and `weekly_look`. Fin's notices are new to the user: leave their push off until the user turns it on." }, "tone": { "type": "string", "enum": [ "needs_you", "problem", "resolved", "neutral" ], "description": "How it reads, to tint its icon: `needs_you` while an approval or a question waits for the user, when fin paused an automation until its owner acts, or when an automation's approval ends in three days; `problem` when something went wrong (a trade or a withdrawal that didn't go through, a refunded deposit, an automation that can't check its data or run, a reply that failed) or fin noticed a fall in the user's money; `resolved` when an automation's problem is over; `neutral` otherwise." }, "title": { "type": "string", "description": "The title to show, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." }, "withoutAmounts": { "type": "object", "properties": { "title": { "type": "string", "description": "The notification's title, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." } }, "required": [ "title", "body" ], "description": "The same notification without amounts, for a lock screen or anywhere the user asked you not to show them." }, "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "An approval waiting for the user.", "enum": [ "approval" ] }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the approval is in." } }, "required": [ "type", "approvalId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A question fin asked the user.", "enum": [ "question" ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The question's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the question is in." } }, "required": [ "type", "questionId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A run an automation started.", "enum": [ "automation_run" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id, as Get an automation run takes it." } }, "required": [ "type", "automationId", "automationRunId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A trade the agent made.", "enum": [ "trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id, as Get a trade takes it." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A swap the user made in the agent wallet.", "enum": [ "swap" ] }, "swapId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id, as Get a swap takes it." } }, "required": [ "type", "swapId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A buy or a sale of a Solana token, by the user on its page or by the agent.", "enum": [ "solana_trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "For a trade the user placed on the token's page, its id as Get a Solana trade takes it; for one the agent made, the id of its `solana` item in List activity." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A Polymarket order.", "enum": [ "prediction_order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a prediction order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A limit order.", "enum": [ "order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a limit order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A deposit into the agent wallet.", "enum": [ "deposit" ] }, "depositId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id, as Get a deposit takes it." } }, "required": [ "type", "depositId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A transfer to a deposit address.", "enum": [ "deposit_address" ] }, "depositAddressId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id, as Get a deposit address takes it." } }, "required": [ "type", "depositAddressId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A withdrawal from the agent wallet.", "enum": [ "withdrawal" ] }, "withdrawalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id, as Get a withdrawal takes it." } }, "required": [ "type", "withdrawalId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "An automation as a whole.", "enum": [ "automation" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." } }, "required": [ "type", "automationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "fin's reply in a conversation.", "enum": [ "conversation" ] }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run that replied." } }, "required": [ "type", "conversationId", "runId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A market story fin's news desk is carrying.", "enum": [ "story" ] }, "storyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The story's id, as Get a market story takes it." } }, "required": [ "type", "storyId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A coin or token the user holds.", "enum": [ "asset" ] }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEAR Intents asset id, or `solana:` for a Solana token." } }, "required": [ "type", "assetId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The user's money over one week, as fin looked at it.", "enum": [ "week" ] }, "weekOf": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The Monday the week began, as an ISO date." } }, "required": [ "type", "weekOf" ] } ], "description": "What the notification is about. Open its page when the user opens the notification." }, "tokenId": { "description": "The token the notification is about, to draw its icon beside the text: what a trade or order bought (or sold, when it received dollars), or what a deposit brought or a withdrawal sent. A NEAR Intents asset id, or `solana:` for a Solana token. Absent for the other kinds, and when Fin cannot name the token.", "type": "string", "minLength": 1, "maxLength": 256 }, "status": { "description": "For an approval or a question: `waiting` while the user can still answer, `expired` once it ran out, `done` once it was answered. `waiting` also marks an `automation_attention` for an automation fin paused until its owner acts, which has no `expiresAt` and reads `done` once they have. Absent otherwise.", "type": "string", "enum": [ "waiting", "expired", "done" ] }, "action": { "description": "On an automation fin paused for its owner (`status` `waiting`), what moves it on: `add_funds` or `edit_automation`. Absent when the owner moves it on from the automation's page, by a choice or by resuming it, and on every other notification.", "type": "string", "enum": [ "add_funds", "edit_automation" ] }, "expiresAt": { "description": "For an approval or a question that is waiting: when it runs out.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "options": { "description": "Ways to act on one of fin's own notices (`holding_move`, `market_story`, `weekly_look`), best first. Show them where the user opens the notification, never in a push or on a lock screen, under a line saying they are options, not recommendations, and that doing nothing is fine. Absent on every other notification.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/NotificationOption" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened." }, "readAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user read it, or when its approval or question was answered or ran out; null while unread." }, "userId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your identifier for this user: unique within your partner, 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. It appears in URLs, so never use an email address or other personal data." }, "push": { "type": "boolean", "description": "Whether to show it on the user's devices now: true unless the user already saw it, or its approval or question was answered or ran out while it waited." } }, "required": [ "id", "kind", "category", "tone", "title", "body", "withoutAmounts", "subject", "createdAt", "readAt", "userId", "push" ] }, "description": "Your users' notifications, oldest first." }, "nextCursor": { "type": "string", "description": "Where this page ended. Keep it, and pass it back as `after` on your next call, even when this page was empty." } }, "required": [ "data", "nextCursor" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "partner.notifications", "summary": "List notifications to deliver", "tags": [ "partner" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "after", "required": false, "description": "The `nextCursor` from your previous call; omit to start from the beginning." }, { "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 }, "in": "query", "name": "limit", "required": false, "description": "How many notifications to return, at most 500." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Your users' notifications after your cursor, and where this page ended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The notification's id." }, "kind": { "type": "string", "enum": [ "approval", "question", "automation_report", "trade", "order_filled", "deposit", "withdrawal", "automation_attention", "reply", "holding_move", "market_story", "weekly_look" ], "description": "What happened: an `approval` or `question` waiting for the user, an `automation_report`, a `trade` that ended (one an automation made, one the agent made in chat, the user's own swap, or a Solana buy or sale, the user's own on the token's page included), an `order_filled` (a limit order or a Polymarket order), a `deposit`, a `withdrawal`, an `automation_attention` problem with an automation, fin's `reply` in a chat the user left, or one of fin's own notices about what it noticed: a `holding_move` (a coin that is a real part of the user's money fell far more than it usually does, or their whole money fell 5% in a day), a `market_story` (big news about a coin they hold) or a `weekly_look` (fin's look at their week). Fin may add kinds: show one you do not know by its `title` and `body`." }, "category": { "type": "string", "enum": [ "needs_you", "alerts_and_reports", "money_moved", "automation_problems", "replies", "big_news", "big_moves", "weekly_look" ], "description": "Which of the user's notification settings it falls under, if your app lets them choose: `needs_you`, `alerts_and_reports`, `money_moved`, `automation_problems`, `replies`, or, for fin's own notices, `big_news`, `big_moves` and `weekly_look`. Fin's notices are new to the user: leave their push off until the user turns it on." }, "tone": { "type": "string", "enum": [ "needs_you", "problem", "resolved", "neutral" ], "description": "How it reads, to tint its icon: `needs_you` while an approval or a question waits for the user, when fin paused an automation until its owner acts, or when an automation's approval ends in three days; `problem` when something went wrong (a trade or a withdrawal that didn't go through, a refunded deposit, an automation that can't check its data or run, a reply that failed) or fin noticed a fall in the user's money; `resolved` when an automation's problem is over; `neutral` otherwise." }, "title": { "type": "string", "description": "The title to show, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." }, "withoutAmounts": { "type": "object", "properties": { "title": { "type": "string", "description": "The notification's title, plain text." }, "body": { "type": "string", "description": "One line under the title, plain text." } }, "required": [ "title", "body" ], "description": "The same notification without amounts, for a lock screen or anywhere the user asked you not to show them." }, "subject": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "An approval waiting for the user.", "enum": [ "approval" ] }, "approvalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The approval's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the approval is in." } }, "required": [ "type", "approvalId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A question fin asked the user.", "enum": [ "question" ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The question's id." }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation the question is in." } }, "required": [ "type", "questionId", "conversationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A run an automation started.", "enum": [ "automation_run" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "automationRunId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run's id, as Get an automation run takes it." } }, "required": [ "type", "automationId", "automationRunId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A trade the agent made.", "enum": [ "trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The trade's id, as Get a trade takes it." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A swap the user made in the agent wallet.", "enum": [ "swap" ] }, "swapId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The swap's id, as Get a swap takes it." } }, "required": [ "type", "swapId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A buy or a sale of a Solana token, by the user on its page or by the agent.", "enum": [ "solana_trade" ] }, "tradeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "For a trade the user placed on the token's page, its id as Get a Solana trade takes it; for one the agent made, the id of its `solana` item in List activity." } }, "required": [ "type", "tradeId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A Polymarket order.", "enum": [ "prediction_order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a prediction order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A limit order.", "enum": [ "order" ] }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The order's id, as Get a limit order takes it." } }, "required": [ "type", "orderId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A deposit into the agent wallet.", "enum": [ "deposit" ] }, "depositId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit's id, as Get a deposit takes it." } }, "required": [ "type", "depositId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A transfer to a deposit address.", "enum": [ "deposit_address" ] }, "depositAddressId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The deposit address's id, as Get a deposit address takes it." } }, "required": [ "type", "depositAddressId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A withdrawal from the agent wallet.", "enum": [ "withdrawal" ] }, "withdrawalId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The withdrawal's id, as Get a withdrawal takes it." } }, "required": [ "type", "withdrawalId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "An automation as a whole.", "enum": [ "automation" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." } }, "required": [ "type", "automationId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "fin's reply in a conversation.", "enum": [ "conversation" ] }, "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The run that replied." } }, "required": [ "type", "conversationId", "runId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A market story fin's news desk is carrying.", "enum": [ "story" ] }, "storyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The story's id, as Get a market story takes it." } }, "required": [ "type", "storyId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "A coin or token the user holds.", "enum": [ "asset" ] }, "assetId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The asset's NEAR Intents asset id, or `solana:` for a Solana token." } }, "required": [ "type", "assetId" ] }, { "type": "object", "properties": { "type": { "type": "string", "description": "The user's money over one week, as fin looked at it.", "enum": [ "week" ] }, "weekOf": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The Monday the week began, as an ISO date." } }, "required": [ "type", "weekOf" ] } ], "description": "What the notification is about. Open its page when the user opens the notification." }, "tokenId": { "description": "The token the notification is about, to draw its icon beside the text: what a trade or order bought (or sold, when it received dollars), or what a deposit brought or a withdrawal sent. A NEAR Intents asset id, or `solana:` for a Solana token. Absent for the other kinds, and when Fin cannot name the token.", "type": "string", "minLength": 1, "maxLength": 256 }, "status": { "description": "For an approval or a question: `waiting` while the user can still answer, `expired` once it ran out, `done` once it was answered. `waiting` also marks an `automation_attention` for an automation fin paused until its owner acts, which has no `expiresAt` and reads `done` once they have. Absent otherwise.", "type": "string", "enum": [ "waiting", "expired", "done" ] }, "action": { "description": "On an automation fin paused for its owner (`status` `waiting`), what moves it on: `add_funds` or `edit_automation`. Absent when the owner moves it on from the automation's page, by a choice or by resuming it, and on every other notification.", "type": "string", "enum": [ "add_funds", "edit_automation" ] }, "expiresAt": { "description": "For an approval or a question that is waiting: when it runs out.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "options": { "description": "Ways to act on one of fin's own notices (`holding_move`, `market_story`, `weekly_look`), best first. Show them where the user opens the notification, never in a push or on a lock screen, under a line saying they are options, not recommendations, and that doing nothing is fine. Absent on every other notification.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/NotificationOption" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it happened." }, "readAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the user read it, or when its approval or question was answered or ran out; null while unread." }, "userId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your identifier for this user: unique within your partner, 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. It appears in URLs, so never use an email address or other personal data." }, "push": { "type": "boolean", "description": "Whether to show it on the user's devices now: true unless the user already saw it, or its approval or question was answered or ran out while it waited." } }, "required": [ "id", "kind", "category", "tone", "title", "body", "withoutAmounts", "subject", "createdAt", "readAt", "userId", "push" ] }, "description": "Your users' notifications, oldest first." }, "nextCursor": { "type": "string", "description": "Where this page ended. Keep it, and pass it back as `after` on your next call, even when this page was empty." } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "NotificationOption": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The option, verb first: `Protect the rest`." }, "detail": { "type": "string", "minLength": 1, "maxLength": 140, "description": "Its terms in one line: `Sell only if it falls another 5%, to $1,696.`" }, "button": { "type": "string", "minLength": 1, "maxLength": 24, "description": "Its button's label: `Set it`." }, "review": { "oneOf": [ { "$ref": "#/components/schemas/AskReview" }, { "$ref": "#/components/schemas/OpenReview" } ], "description": "What choosing it does: `ask` opens fin's chat with `question` as the user's message, and fin proposes and waits for the user's approval as always; `open` opens a product's own form, filled in (`targetId` `earn`: Earn, with the amount to put in)." } }, "required": [ "title", "detail", "button", "review" ], "description": "One way to act on one of fin's notices. It only opens fin's chat or a form: nothing moves until the user approves it." }, "AskReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "ask", "description": "Which review this is." }, "question": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The question the chat opens with." } }, "required": [ "kind", "question" ], "description": "Ask Fin: opens the page's chat with the question." }, "OpenReview": { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Which review this is." }, "targetId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Your app's id for the form." }, "amount": { "description": "What Fin fills in.", "$ref": "#/components/schemas/AssetAmount" } }, "required": [ "kind", "targetId" ], "description": "A product Fin cannot run for you: its own form, filled in. Fin does not suggest it yet." }, "AssetAmount": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/ReviewAsset" }, "amountRaw": { "type": "string", "maxLength": 78, "pattern": "^(0|[1-9][0-9]*)$", "description": "In the asset's smallest unit, as a decimal integer string: `3000000` is 3 USDC." } }, "required": [ "asset", "amountRaw" ], "description": "An exact amount of one asset." }, "ReviewAsset": { "type": "object", "properties": { "assetId": { "type": "string", "pattern": "^asset_[a-f0-9]{64}$", "description": "The asset as Get balances and Prepare an order name it." }, "symbol": { "type": "string", "minLength": 1, "maxLength": 32, "description": "The asset's symbol: `NEAR`, `USDC`, `BTC`, `AAPL`." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36, "description": "The asset's own scale: 24 for NEAR, 6 for USDC, 8 for BTC." }, "network": { "description": "The chain it sits on, for its badge: `near`, `base`; omitted for none.", "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" } }, "required": [ "assetId", "symbol", "decimals" ], "description": "An asset a review names, as it draws and prints it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # List market subjects 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. `GET /v1/market/subjects` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "enum": [ "market", "chain", "asset", "stock" ] }, "in": "query", "name": "kind", "required": false, "description": "Only subjects of this kind." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "alias", "required": false, "description": "Only the subjects this identifier names." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/market/subjects' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 The subjects market briefs cover. ```json { "description": "The subjects market briefs cover.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketSubjects" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `market_briefs_disabled` — market briefs are not turned on for your partner key ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `market_briefs_disabled` — market briefs are not turned on for your partner key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "market.subjects.list", "summary": "List market subjects", "tags": [ "market" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "enum": [ "market", "chain", "asset", "stock" ] }, "in": "query", "name": "kind", "required": false, "description": "Only subjects of this kind." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "alias", "required": false, "description": "Only the subjects this identifier names." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The subjects market briefs cover.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketSubjects" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `market_briefs_disabled` — market briefs are not turned on for your partner key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "MarketSubjects": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketSubject" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ], "description": "Subjects market briefs cover." }, "MarketSubject": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "kind": { "type": "string", "enum": [ "market", "chain", "asset", "stock" ], "description": "What kind of subject it is." }, "name": { "type": "string", "description": "Its name." }, "symbol": { "description": "Its symbol, if it has one.", "type": [ "string", "null" ] }, "chains": { "type": "array", "items": { "type": "string" }, "description": "The chains an asset trades on; the chain itself for a chain." }, "aliases": { "type": "array", "items": { "type": "string" }, "description": "Other identifiers that name it: CoinGecko ids, symbols, contract addresses, 1Click asset ids." } }, "required": [ "id", "kind", "name", "symbol", "chains", "aliases" ], "description": "Something a market brief can be about." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # Create a market brief 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`. `POST /v1/market/briefs` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Header parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMarketBriefInputInput" } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/market/briefs' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'idempotency-key: d5565100-9342-4bc6-a803-b387a20cb536' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The brief, finished at once. ```json { "description": "The brief, finished at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketBriefJob" } } } } ``` ### 202 The brief job, generating. ```json { "description": "The brief job, generating.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketBriefJob" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `scope_invalid` — a subject in the scope is not a subject id, or appears twice ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `scope_invalid` — a subject in the scope is not a subject id, or appears twice", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `market_briefs_disabled` — market briefs are not turned on for your partner key ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `market_briefs_disabled` — market briefs are not turned on for your partner key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. - `subject_unsupported` — a subject in the scope is not one market briefs cover; list them with List market subjects ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `subject_unsupported` — a subject in the scope is not one market briefs cover; list them with List market subjects", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request ```json { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After - `briefs_busy` — your market briefs are at their limit of briefs generating at once; retry after `Retry-After` - `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `briefs_busy` — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "market.briefs.create", "summary": "Create a market brief", "tags": [ "market" ], "description": "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`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMarketBriefInputInput" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "example": "d5565100-9342-4bc6-a803-b387a20cb536", "in": "header", "name": "idempotency-key", "required": true, "description": "A UUID you generate for this request. Send the same key and the same body to retry it safely: you get the original result back, never a second one. A different body under the same key is refused with `request_key_conflict`." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The brief, finished at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketBriefJob" } } } }, "202": { "description": "The brief job, generating.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketBriefJob" } } } }, "400": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `scope_invalid` — a subject in the scope is not a subject id, or appears twice", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `market_briefs_disabled` — market briefs are not turned on for your partner key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `subject_unsupported` — a subject in the scope is not one market briefs cover; list them with List market subjects", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "The operation lost to the current state.\n\n- `request_key_conflict` — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `briefs_busy` — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `budget_exhausted` — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "CreateMarketBriefInputInput": { "type": "object", "properties": { "scope": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "description": "The subjects to research together, one to ten, in any order." }, "window": { "type": "string", "enum": [ "24h" ], "description": "The window the brief explains. Only `24h` today." }, "mode": { "description": "Use `news` to research even a quiet price move; `auto`, the default, may return a free quiet brief.", "type": "string", "enum": [ "auto", "news" ] } }, "required": [ "scope", "window" ], "additionalProperties": false, "description": "What a market brief should explain." }, "MarketBriefJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The brief job's id." }, "scope": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "description": "The subjects, sorted: with `window`, a natural key to cache a brief by." }, "window": { "type": "string", "enum": [ "24h" ], "description": "The window the brief explains." }, "mode": { "description": "The requested research mode; absent on older jobs means `auto`.", "type": "string", "enum": [ "auto", "news" ] }, "status": { "type": "string", "enum": [ "generating", "ready", "failed" ], "description": "`generating` until the brief is `ready` or the job has `failed`." }, "retryAfterSeconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "While generating, how long to wait before reading the job again." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the job was created." }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the job finished." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "generation_failed", "brief_invalid", "budget_exhausted" ], "description": "Why the job failed." }, "details": { "description": "A safe failure category and retry guidance, without provider error text.", "type": "object", "properties": { "stage": { "type": "string", "enum": [ "admission", "research", "synthesis", "validation", "deadline" ] }, "reason": { "type": "string", "enum": [ "unavailable", "invalid_output", "budget_exhausted", "deadline_exceeded" ] }, "retryable": { "type": "boolean", "description": "Whether a deliberate new request may succeed; reusing this job's key still returns this outcome." } }, "required": [ "stage", "reason", "retryable" ] } }, "required": [ "code" ] }, { "type": "null" } ], "description": "Why the job failed, once it has." }, "costCents": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "null" } ], "description": "The settled model cost of making the brief, in integer cents, once the job finished; a quiet brief costs nothing." }, "brief": { "anyOf": [ { "$ref": "#/components/schemas/MarketBrief" }, { "type": "null" } ], "description": "The brief, once ready." } }, "required": [ "id", "scope", "window", "status", "retryAfterSeconds", "createdAt", "completedAt", "failure", "costCents", "brief" ], "description": "One market brief request and its outcome, kept 30 days for the partner that created it." }, "MarketBrief": { "type": "object", "properties": { "headline": { "type": "string", "maxLength": 120, "description": "One line on what happened, in words." }, "summary": { "type": "string", "maxLength": 600, "description": "Two or three sentences, in words." }, "explained": { "type": "boolean", "description": "The brief's aggregate explanation flag, not a verdict for every subject. Use research.coverage for each subject's search and explanation outcome." }, "evidence": { "description": "Exact quote witnesses from the assistive review of headline and summary; server-written abstention can have none.", "type": "object", "properties": { "headline": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "sourceId": { "type": "string", "maxLength": 16 }, "quote": { "type": "string", "maxLength": 200 } }, "required": [ "sourceId", "quote" ] } }, "summary": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "sourceId": { "type": "string", "maxLength": 16 }, "quote": { "type": "string", "maxLength": 200 } }, "required": [ "sourceId", "quote" ] } } }, "required": [ "headline", "summary" ] }, "research": { "description": "Whether research ran and what evidence it supplied for each subject; absent on older briefs.", "type": "object", "properties": { "performed": { "type": "boolean", "description": "Whether news research ran for this brief." }, "skipReason": { "description": "Why research was skipped.", "type": "string", "const": "quiet" }, "coverage": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "searchStatus": { "type": "string", "enum": [ "not_searched", "complete", "partial", "unavailable" ], "description": "`complete` means the planned searches finished, not that every possible source was searched." }, "explanationStatus": { "type": "string", "enum": [ "possible_driver", "context_only", "unexplained" ], "description": "What the reviewed evidence supports for this subject, separately from search completion." }, "sourceIds": { "type": "array", "items": { "type": "string", "maxLength": 16 } } }, "required": [ "subject", "searchStatus", "explanationStatus", "sourceIds" ] } } }, "required": [ "performed", "coverage" ] }, "moves": { "type": "array", "items": { "$ref": "#/components/schemas/MarketMove" }, "description": "Each subject's figures, in scope order." }, "drivers": { "type": "array", "items": { "$ref": "#/components/schemas/MarketDriver" }, "description": "The reasons, shared ones first." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/MarketSource" }, "description": "Every source a reason cites." }, "generatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin finished the brief." }, "pipelineVersion": { "type": "string", "description": "Which prompt and checks produced the brief." } }, "required": [ "headline", "summary", "explained", "moves", "drivers", "sources", "generatedAt", "pipelineVersion" ], "description": "What part of the market did over a window, and why, with sources. Every figure is Fin's; the words are a model's, checked." }, "MarketMove": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "magnitude": { "anyOf": [ { "type": "string", "enum": [ "quiet", "notable", "large" ] }, { "type": "null" } ], "description": "How the subject's 24-hour price move compares with its usual daily move; null without enough price history." }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MarketMetric" }, "description": "Fin's own figures for the subject." } }, "required": [ "subject", "magnitude", "metrics" ], "description": "What one subject did over the window." }, "MarketMetric": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "What is measured: price, volume, total_market_cap, btc_dominance or tvl today. New names can appear: show the ones you know and skip the rest." }, "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "The measured value as an exact decimal: USD for price, volume, market cap and TVL; percent for dominance." }, "unit": { "description": "The value's unit, when this release supplies it.", "type": "string", "enum": [ "usd", "percent" ] }, "provenance": { "description": "The identity, providers and actual observation times behind the figure.", "type": "object", "properties": { "provider": { "description": "The provider of the current value, when known.", "type": [ "string", "null" ] }, "referenceTokenId": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "The reference token measured, when a token price is used." }, "coingeckoId": { "description": "The CoinGecko asset identity, when applicable.", "type": [ "string", "null" ] }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "The provider's observation time; null when it was not supplied." }, "asOfBasis": { "type": "string", "enum": [ "provider", "retrieval", "generation" ], "description": "Whether `asOf` is a provider observation, a retrieval time or the brief's assembly time." }, "comparison": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "USD per whole unit of the measured asset or reference token." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The provider's observation time." }, "provider": { "type": "string", "description": "The provider that supplied this observation." } }, "required": [ "value", "observedAt", "provider" ] }, "end": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "USD per whole unit of the measured asset or reference token." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The provider's observation time." }, "provider": { "type": "string", "description": "The provider that supplied this observation." } }, "required": [ "value", "observedAt", "provider" ] } }, "required": [ "start", "end" ] }, { "type": "null" } ], "description": "The actual price observations used for the percentage change; null for a provider-reported change or a level." } }, "required": [ "provider", "referenceTokenId", "coingeckoId", "observedAt", "asOfBasis", "comparison" ] }, "changePct": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, { "type": "null" } ], "description": "The change over the window, in percent; null when the source gives only a level." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The figure's timestamp; inspect provenance.asOfBasis to distinguish a provider observation from retrieval or assembly time." }, "benchmark": { "anyOf": [ { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "changePct": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "The benchmark's change over the window, in percent." }, "provenance": { "type": "object", "properties": { "provider": { "description": "The provider of the current value, when known.", "type": [ "string", "null" ] }, "referenceTokenId": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "The reference token measured, when a token price is used." }, "coingeckoId": { "description": "The CoinGecko asset identity, when applicable.", "type": [ "string", "null" ] }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "The provider's observation time; null when it was not supplied." }, "asOfBasis": { "type": "string", "enum": [ "provider", "retrieval", "generation" ], "description": "Whether `asOf` is a provider observation, a retrieval time or the brief's assembly time." }, "comparison": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "USD per whole unit of the measured asset or reference token." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The provider's observation time." }, "provider": { "type": "string", "description": "The provider that supplied this observation." } }, "required": [ "value", "observedAt", "provider" ] }, "end": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "USD per whole unit of the measured asset or reference token." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The provider's observation time." }, "provider": { "type": "string", "description": "The provider that supplied this observation." } }, "required": [ "value", "observedAt", "provider" ] } }, "required": [ "start", "end" ] }, { "type": "null" } ], "description": "The actual price observations used for the percentage change; null for a provider-reported change or a level." } }, "required": [ "provider", "referenceTokenId", "coingeckoId", "observedAt", "asOfBasis", "comparison" ] } }, "required": [ "subject", "changePct" ] }, { "type": "null" } ], "description": "What the subject's price change is compared with: bitcoin for crypto, the S&P 500 ETF for stocks." } }, "required": [ "name", "value", "changePct", "asOf", "benchmark" ], "description": "One figure Fin measured, never one the model wrote." }, "MarketDriver": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 300, "description": "One reason, in words." }, "eventAt": { "description": "Actual event time established by a quoted passage; unknown for context.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "classification": { "description": "Evidence-reviewed context or a qualified possible driver; causality is not proven.", "type": "string", "enum": [ "possible_driver", "context_only" ] }, "evidence": { "description": "Exact short source passages supporting this reason.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "sourceId": { "type": "string", "maxLength": 16 }, "quote": { "type": "string", "maxLength": 200 } }, "required": [ "sourceId", "quote" ] } }, "subjects": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "description": "The subjects this reason explains." }, "sourceIds": { "maxItems": 4, "type": "array", "items": { "type": "string", "maxLength": 16 }, "description": "The ids of the sources this reason rests on." } }, "required": [ "text", "subjects", "sourceIds" ], "description": "One reason a move happened, with its sources." }, "MarketSource": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16, "description": "The source's id within this brief." }, "title": { "type": "string", "description": "The source's headline." }, "publisher": { "description": "Who published it.", "type": [ "string", "null" ] }, "url": { "type": "string", "maxLength": 2048, "description": "Where to read it." }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was published, if known." }, "publishedAtBasis": { "description": "How the publication clock was obtained; an estimate may instead be an update.", "type": [ "string", "null" ] }, "retrievedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "eventAt": { "description": "Actual event time when source evidence establishes it; publication alone is insufficient.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "sourceKind": { "type": "string" }, "evidenceLevel": { "type": "string", "enum": [ "title_only", "search_excerpt", "provider_raw_content" ] }, "excerpt": { "description": "A bounded permitted supporting passage; absent for publishers whose text cannot be relayed.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "id", "title", "publisher", "url", "publishedAt" ], "description": "A news item a reason cites." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # Get a market brief Answers a brief job your partner key created: `generating`, then `ready` with the brief, or `failed` with why. `GET /v1/market/briefs/{id}` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Path parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "The brief job's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/market/briefs/YOUR_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 The brief job. ```json { "description": "The brief job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketBriefJob" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call - `market_briefs_disabled` — market briefs are not turned on for your partner key ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `market_briefs_disabled` — market briefs are not turned on for your partner key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. - `brief_not_found` — no market brief job with this id was created with your partner key ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `brief_not_found` — no market brief job with this id was created with your partner key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "market.briefs.get", "summary": "Get a market brief", "tags": [ "market" ], "description": "Answers a brief job your partner key created: `generating`, then `ready` with the brief, or `failed` with why.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "The brief job's id." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The brief job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketBriefJob" } } } }, "400": { "$ref": "#/components/responses/InvalidInputForRegistration" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call\n- `market_briefs_disabled` — market briefs are not turned on for your partner key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `brief_not_found` — no market brief job with this id was created with your partner key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "MarketBriefJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The brief job's id." }, "scope": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "description": "The subjects, sorted: with `window`, a natural key to cache a brief by." }, "window": { "type": "string", "enum": [ "24h" ], "description": "The window the brief explains." }, "mode": { "description": "The requested research mode; absent on older jobs means `auto`.", "type": "string", "enum": [ "auto", "news" ] }, "status": { "type": "string", "enum": [ "generating", "ready", "failed" ], "description": "`generating` until the brief is `ready` or the job has `failed`." }, "retryAfterSeconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "While generating, how long to wait before reading the job again." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the job was created." }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the job finished." }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "generation_failed", "brief_invalid", "budget_exhausted" ], "description": "Why the job failed." }, "details": { "description": "A safe failure category and retry guidance, without provider error text.", "type": "object", "properties": { "stage": { "type": "string", "enum": [ "admission", "research", "synthesis", "validation", "deadline" ] }, "reason": { "type": "string", "enum": [ "unavailable", "invalid_output", "budget_exhausted", "deadline_exceeded" ] }, "retryable": { "type": "boolean", "description": "Whether a deliberate new request may succeed; reusing this job's key still returns this outcome." } }, "required": [ "stage", "reason", "retryable" ] } }, "required": [ "code" ] }, { "type": "null" } ], "description": "Why the job failed, once it has." }, "costCents": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "null" } ], "description": "The settled model cost of making the brief, in integer cents, once the job finished; a quiet brief costs nothing." }, "brief": { "anyOf": [ { "$ref": "#/components/schemas/MarketBrief" }, { "type": "null" } ], "description": "The brief, once ready." } }, "required": [ "id", "scope", "window", "status", "retryAfterSeconds", "createdAt", "completedAt", "failure", "costCents", "brief" ], "description": "One market brief request and its outcome, kept 30 days for the partner that created it." }, "MarketBrief": { "type": "object", "properties": { "headline": { "type": "string", "maxLength": 120, "description": "One line on what happened, in words." }, "summary": { "type": "string", "maxLength": 600, "description": "Two or three sentences, in words." }, "explained": { "type": "boolean", "description": "The brief's aggregate explanation flag, not a verdict for every subject. Use research.coverage for each subject's search and explanation outcome." }, "evidence": { "description": "Exact quote witnesses from the assistive review of headline and summary; server-written abstention can have none.", "type": "object", "properties": { "headline": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "sourceId": { "type": "string", "maxLength": 16 }, "quote": { "type": "string", "maxLength": 200 } }, "required": [ "sourceId", "quote" ] } }, "summary": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "sourceId": { "type": "string", "maxLength": 16 }, "quote": { "type": "string", "maxLength": 200 } }, "required": [ "sourceId", "quote" ] } } }, "required": [ "headline", "summary" ] }, "research": { "description": "Whether research ran and what evidence it supplied for each subject; absent on older briefs.", "type": "object", "properties": { "performed": { "type": "boolean", "description": "Whether news research ran for this brief." }, "skipReason": { "description": "Why research was skipped.", "type": "string", "const": "quiet" }, "coverage": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "searchStatus": { "type": "string", "enum": [ "not_searched", "complete", "partial", "unavailable" ], "description": "`complete` means the planned searches finished, not that every possible source was searched." }, "explanationStatus": { "type": "string", "enum": [ "possible_driver", "context_only", "unexplained" ], "description": "What the reviewed evidence supports for this subject, separately from search completion." }, "sourceIds": { "type": "array", "items": { "type": "string", "maxLength": 16 } } }, "required": [ "subject", "searchStatus", "explanationStatus", "sourceIds" ] } } }, "required": [ "performed", "coverage" ] }, "moves": { "type": "array", "items": { "$ref": "#/components/schemas/MarketMove" }, "description": "Each subject's figures, in scope order." }, "drivers": { "type": "array", "items": { "$ref": "#/components/schemas/MarketDriver" }, "description": "The reasons, shared ones first." }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/MarketSource" }, "description": "Every source a reason cites." }, "generatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin finished the brief." }, "pipelineVersion": { "type": "string", "description": "Which prompt and checks produced the brief." } }, "required": [ "headline", "summary", "explained", "moves", "drivers", "sources", "generatedAt", "pipelineVersion" ], "description": "What part of the market did over a window, and why, with sources. Every figure is Fin's; the words are a model's, checked." }, "MarketMove": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "magnitude": { "anyOf": [ { "type": "string", "enum": [ "quiet", "notable", "large" ] }, { "type": "null" } ], "description": "How the subject's 24-hour price move compares with its usual daily move; null without enough price history." }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MarketMetric" }, "description": "Fin's own figures for the subject." } }, "required": [ "subject", "magnitude", "metrics" ], "description": "What one subject did over the window." }, "MarketMetric": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40, "description": "What is measured: price, volume, total_market_cap, btc_dominance or tvl today. New names can appear: show the ones you know and skip the rest." }, "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "The measured value as an exact decimal: USD for price, volume, market cap and TVL; percent for dominance." }, "unit": { "description": "The value's unit, when this release supplies it.", "type": "string", "enum": [ "usd", "percent" ] }, "provenance": { "description": "The identity, providers and actual observation times behind the figure.", "type": "object", "properties": { "provider": { "description": "The provider of the current value, when known.", "type": [ "string", "null" ] }, "referenceTokenId": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "The reference token measured, when a token price is used." }, "coingeckoId": { "description": "The CoinGecko asset identity, when applicable.", "type": [ "string", "null" ] }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "The provider's observation time; null when it was not supplied." }, "asOfBasis": { "type": "string", "enum": [ "provider", "retrieval", "generation" ], "description": "Whether `asOf` is a provider observation, a retrieval time or the brief's assembly time." }, "comparison": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "USD per whole unit of the measured asset or reference token." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The provider's observation time." }, "provider": { "type": "string", "description": "The provider that supplied this observation." } }, "required": [ "value", "observedAt", "provider" ] }, "end": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "USD per whole unit of the measured asset or reference token." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The provider's observation time." }, "provider": { "type": "string", "description": "The provider that supplied this observation." } }, "required": [ "value", "observedAt", "provider" ] } }, "required": [ "start", "end" ] }, { "type": "null" } ], "description": "The actual price observations used for the percentage change; null for a provider-reported change or a level." } }, "required": [ "provider", "referenceTokenId", "coingeckoId", "observedAt", "asOfBasis", "comparison" ] }, "changePct": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$" }, { "type": "null" } ], "description": "The change over the window, in percent; null when the source gives only a level." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The figure's timestamp; inspect provenance.asOfBasis to distinguish a provider observation from retrieval or assembly time." }, "benchmark": { "anyOf": [ { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "changePct": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "The benchmark's change over the window, in percent." }, "provenance": { "type": "object", "properties": { "provider": { "description": "The provider of the current value, when known.", "type": [ "string", "null" ] }, "referenceTokenId": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "The reference token measured, when a token price is used." }, "coingeckoId": { "description": "The CoinGecko asset identity, when applicable.", "type": [ "string", "null" ] }, "observedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "The provider's observation time; null when it was not supplied." }, "asOfBasis": { "type": "string", "enum": [ "provider", "retrieval", "generation" ], "description": "Whether `asOf` is a provider observation, a retrieval time or the brief's assembly time." }, "comparison": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "USD per whole unit of the measured asset or reference token." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The provider's observation time." }, "provider": { "type": "string", "description": "The provider that supplied this observation." } }, "required": [ "value", "observedAt", "provider" ] }, "end": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?$", "description": "USD per whole unit of the measured asset or reference token." }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The provider's observation time." }, "provider": { "type": "string", "description": "The provider that supplied this observation." } }, "required": [ "value", "observedAt", "provider" ] } }, "required": [ "start", "end" ] }, { "type": "null" } ], "description": "The actual price observations used for the percentage change; null for a provider-reported change or a level." } }, "required": [ "provider", "referenceTokenId", "coingeckoId", "observedAt", "asOfBasis", "comparison" ] } }, "required": [ "subject", "changePct" ] }, { "type": "null" } ], "description": "What the subject's price change is compared with: bitcoin for crypto, the S&P 500 ETF for stocks." } }, "required": [ "name", "value", "changePct", "asOf", "benchmark" ], "description": "One figure Fin measured, never one the model wrote." }, "MarketDriver": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 300, "description": "One reason, in words." }, "eventAt": { "description": "Actual event time established by a quoted passage; unknown for context.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "classification": { "description": "Evidence-reviewed context or a qualified possible driver; causality is not proven.", "type": "string", "enum": [ "possible_driver", "context_only" ] }, "evidence": { "description": "Exact short source passages supporting this reason.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "sourceId": { "type": "string", "maxLength": 16 }, "quote": { "type": "string", "maxLength": 200 } }, "required": [ "sourceId", "quote" ] } }, "subjects": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A subject's id: `market`, `chain:`, `asset:`, `asset:@` or `stock:`." }, "description": "The subjects this reason explains." }, "sourceIds": { "maxItems": 4, "type": "array", "items": { "type": "string", "maxLength": 16 }, "description": "The ids of the sources this reason rests on." } }, "required": [ "text", "subjects", "sourceIds" ], "description": "One reason a move happened, with its sources." }, "MarketSource": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16, "description": "The source's id within this brief." }, "title": { "type": "string", "description": "The source's headline." }, "publisher": { "description": "Who published it.", "type": [ "string", "null" ] }, "url": { "type": "string", "maxLength": 2048, "description": "Where to read it." }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was published, if known." }, "publishedAtBasis": { "description": "How the publication clock was obtained; an estimate may instead be an update.", "type": [ "string", "null" ] }, "retrievedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "eventAt": { "description": "Actual event time when source evidence establishes it; publication alone is insufficient.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "sourceKind": { "type": "string" }, "evidenceLevel": { "type": "string", "enum": [ "title_only", "search_excerpt", "provider_raw_content" ] }, "excerpt": { "description": "A bounded permitted supporting passage; absent for publishers whose text cannot be relayed.", "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "id", "title", "publisher", "url", "publishedAt" ], "description": "A news item a reason cites." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInputForRegistration": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # List market stories 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 /v1/market/stories` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$" }, "in": "query", "name": "subject", "required": false, "description": "Only stories about this subject: `asset:btc`, `stock:NVDA`." }, { "schema": { "type": "string", "enum": [ "measured", "corroborated", "reported", "unconfirmed" ] }, "in": "query", "name": "evidence", "required": false, "description": "Only stories backed at least this well: `reported` leaves out `unconfirmed`." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/market/stories' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 A page of stories. ```json { "description": "A page of stories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketStories" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "market.stories.list", "summary": "List market stories", "tags": [ "market" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$" }, "in": "query", "name": "subject", "required": false, "description": "Only stories about this subject: `asset:btc`, `stock:NVDA`." }, { "schema": { "type": "string", "enum": [ "measured", "corroborated", "reported", "unconfirmed" ] }, "in": "query", "name": "evidence", "required": false, "description": "Only stories backed at least this well: `reported` leaves out `unconfirmed`." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "A page of stories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketStories" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "MarketStories": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketStory" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ], "description": "Stories the market is telling, most recently confirmed first." }, "MarketStory": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The story's id." }, "title": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The story in a few words." }, "summary": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What happened, in a few sentences." }, "topic": { "anyOf": [ { "type": "string", "enum": [ "security", "legal", "regulation", "governance", "people", "deals", "funding", "launches", "networks", "supply", "economy", "funds", "tokenization", "stablecoins", "predictions", "sports", "ai", "memecoins", "defi", "wallets", "data", "markets" ] }, { "type": "null" } ], "description": "What the story is about, as a reader would file it: `security` (hacks, exploits, scams, thefts and outages); `legal` (lawsuits, courts, criminal charges and settlements); `regulation` (rules, regulators, government policy, licences, taxes and sanctions); `governance` (a DAO's or a protocol's votes and proposals); `people` (a leader joining, leaving or being appointed); `deals` (acquisitions, mergers, sales, IPOs, bankruptcies and shutdowns); `funding` (fundraising and investment rounds); `launches` (a new product, feature, listing, integration or partnership); `networks` (a chain's upgrades, forks, client and node releases); `supply` (token burns, unlocks, airdrops, buybacks and emissions); `economy` (the wider economy: rates, inflation, jobs, central banks and tariffs); `funds` (ETF and fund flows, and companies holding crypto in their treasuries); `tokenization` (tokenized stocks, funds and other real-world assets); `stablecoins` (stablecoins and crypto payments); `predictions` (prediction markets and their odds); `sports` (sports and the markets on them); `ai` (artificial intelligence and AI agents); `memecoins` (memecoins and the launchpads they start on); `defi` (lending, exchanges, yields and other DeFi protocols); `wallets` (wallets, custody and how people sign in); `data` (data, analytics, oracles and research); `markets` (a price, volume, open-interest or liquidity move, or how traders are positioned). Draw a story by it when nothing it names has a logo; null for a story last written before topics." }, "status": { "type": "string", "enum": [ "new", "rising", "steady", "fading" ], "description": "How the story is doing." }, "evidence": { "type": "string", "enum": [ "measured", "corroborated", "reported", "unconfirmed" ], "description": "How well the story is backed." }, "firstSeenAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin first saw the story." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the story was last confirmed by a new source or figure." }, "subjects": { "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/MarketNewsSubject" }, "description": "What the story is about: coins, stocks, prediction markets and the like." }, "sourceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many articles the story rests on." }, "sources": { "maxItems": 3, "type": "array", "items": { "$ref": "#/components/schemas/MarketNewsSource" }, "description": "Its first 3 sources, newest first." } }, "required": [ "id", "title", "summary", "topic", "status", "evidence", "firstSeenAt", "updatedAt", "subjects", "sourceCount", "sources" ], "description": "A story the market is telling." }, "MarketNewsSubject": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$", "description": "What the subject is, as `kind:id`: `asset:btc`, `stock:NVDA`, `prediction:`, `chain:solana`, or `market` for the whole crypto market." }, "kind": { "type": "string", "enum": [ "market", "chain", "asset", "stock", "launchpad", "venue", "pool", "instrument", "fund", "sector", "indicator", "prediction", "account", "publisher", "narrative" ], "description": "What kind of subject it is: `asset` (a coin), `stock`, `prediction` (a prediction market), `chain`, `market`, or a `launchpad`, `venue`, `sector` and the like." }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Its name; for a prediction market, its question." }, "symbol": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "description": "Its ticker or symbol, when it has one." }, "coingeckoId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Its CoinGecko listing, when it has one, by its kind: a coin's (`bitcoin`, `pump-fun`), an exchange's for a venue (`binance`), a category's for a sector (`layer-1`). What its price history and its logo are found by." }, "hyperliquidCoin": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ], "description": "The coin its Hyperliquid market trades as (`BTC`, `PUMP`), when it has one." }, "defillamaId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Its DefiLlama listing, when it has one: a protocol's slug for a venue or launchpad (`uniswap-v3`, `pump.fun`), a chain's name for a chain (`Ethereum`). What its logo is found by." } }, "required": [ "id", "kind", "name", "symbol", "coingeckoId", "hyperliquidCoin", "defillamaId" ], "description": "Something the news is about." }, "MarketNewsSource": { "type": "object", "properties": { "publisher": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Who published it, as their web domain." }, "headline": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Its headline." }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Where to read it." }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was published, when the publisher says." }, "excerpt": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ], "description": "A short excerpt, where the publisher's licence allows one." } }, "required": [ "publisher", "headline", "url", "publishedAt", "excerpt" ], "description": "An article, with where to read it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # Get a market story 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. `GET /v1/market/stories/{storyId}` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Path parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "storyId", "required": true, "description": "The story's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/market/stories/YOUR_STORY_ID' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 The story in full. ```json { "description": "The story in full.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketStoryDetail" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. - `story_not_found` — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `story_not_found` — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "market.stories.get", "summary": "Get a market story", "tags": [ "market" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "storyId", "required": true, "description": "The story's id." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The story in full.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketStoryDetail" } } } }, "400": { "$ref": "#/components/responses/InvalidInputForRegistration" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "404": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.\n\n- `story_not_found` — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "MarketStoryDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The story's id." }, "title": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The story in a few words." }, "summary": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What happened, in a few sentences." }, "topic": { "anyOf": [ { "type": "string", "enum": [ "security", "legal", "regulation", "governance", "people", "deals", "funding", "launches", "networks", "supply", "economy", "funds", "tokenization", "stablecoins", "predictions", "sports", "ai", "memecoins", "defi", "wallets", "data", "markets" ] }, { "type": "null" } ], "description": "What the story is about, as a reader would file it: `security` (hacks, exploits, scams, thefts and outages); `legal` (lawsuits, courts, criminal charges and settlements); `regulation` (rules, regulators, government policy, licences, taxes and sanctions); `governance` (a DAO's or a protocol's votes and proposals); `people` (a leader joining, leaving or being appointed); `deals` (acquisitions, mergers, sales, IPOs, bankruptcies and shutdowns); `funding` (fundraising and investment rounds); `launches` (a new product, feature, listing, integration or partnership); `networks` (a chain's upgrades, forks, client and node releases); `supply` (token burns, unlocks, airdrops, buybacks and emissions); `economy` (the wider economy: rates, inflation, jobs, central banks and tariffs); `funds` (ETF and fund flows, and companies holding crypto in their treasuries); `tokenization` (tokenized stocks, funds and other real-world assets); `stablecoins` (stablecoins and crypto payments); `predictions` (prediction markets and their odds); `sports` (sports and the markets on them); `ai` (artificial intelligence and AI agents); `memecoins` (memecoins and the launchpads they start on); `defi` (lending, exchanges, yields and other DeFi protocols); `wallets` (wallets, custody and how people sign in); `data` (data, analytics, oracles and research); `markets` (a price, volume, open-interest or liquidity move, or how traders are positioned). Draw a story by it when nothing it names has a logo; null for a story last written before topics." }, "status": { "type": "string", "enum": [ "new", "rising", "steady", "fading" ], "description": "How the story is doing." }, "evidence": { "type": "string", "enum": [ "measured", "corroborated", "reported", "unconfirmed" ], "description": "How well the story is backed." }, "firstSeenAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin first saw the story." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the story was last confirmed by a new source or figure." }, "subjects": { "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/MarketNewsSubject" }, "description": "What the story is about: coins, stocks, prediction markets and the like." }, "sourceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many articles the story rests on." }, "sources": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/MarketNewsSource" }, "description": "Every article it rests on, newest first." }, "figures": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/MarketFigure" }, "description": "The market figures the story states, as they read now." }, "moves": { "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/MarketNewsMove" }, "description": "Moves Fin spotted on what the story is about since it began, newest first." } }, "required": [ "id", "title", "summary", "topic", "status", "evidence", "firstSeenAt", "updatedAt", "subjects", "sourceCount", "sources", "figures", "moves" ], "description": "A story the market is telling, in full." }, "MarketNewsSubject": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$", "description": "What the subject is, as `kind:id`: `asset:btc`, `stock:NVDA`, `prediction:`, `chain:solana`, or `market` for the whole crypto market." }, "kind": { "type": "string", "enum": [ "market", "chain", "asset", "stock", "launchpad", "venue", "pool", "instrument", "fund", "sector", "indicator", "prediction", "account", "publisher", "narrative" ], "description": "What kind of subject it is: `asset` (a coin), `stock`, `prediction` (a prediction market), `chain`, `market`, or a `launchpad`, `venue`, `sector` and the like." }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Its name; for a prediction market, its question." }, "symbol": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "description": "Its ticker or symbol, when it has one." }, "coingeckoId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Its CoinGecko listing, when it has one, by its kind: a coin's (`bitcoin`, `pump-fun`), an exchange's for a venue (`binance`), a category's for a sector (`layer-1`). What its price history and its logo are found by." }, "hyperliquidCoin": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ], "description": "The coin its Hyperliquid market trades as (`BTC`, `PUMP`), when it has one." }, "defillamaId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Its DefiLlama listing, when it has one: a protocol's slug for a venue or launchpad (`uniswap-v3`, `pump.fun`), a chain's name for a chain (`Ethereum`). What its logo is found by." } }, "required": [ "id", "kind", "name", "symbol", "coingeckoId", "hyperliquidCoin", "defillamaId" ], "description": "Something the news is about." }, "MarketNewsSource": { "type": "object", "properties": { "publisher": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Who published it, as their web domain." }, "headline": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Its headline." }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Where to read it." }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was published, when the publisher says." }, "excerpt": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ], "description": "A short excerpt, where the publisher's licence allows one." } }, "required": [ "publisher", "headline", "url", "publishedAt", "excerpt" ], "description": "An article, with where to read it." }, "MarketFigure": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/MarketNewsSubject" }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What the figure is, in plain words: `Price`, `Yes odds`, `Trading volume`." }, "unit": { "type": "string", "enum": [ "usd", "usdt", "percent", "points", "count", "ratio", "index", "coin", "btc", "sol" ], "description": "What `value` counts." }, "value": { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The figure now." }, "window": { "type": "string", "minLength": 1, "maxLength": 8, "description": "The window the figure and its change cover: `15m`, `4h`, `1d`, `7d`, `30d`." }, "changePct": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$", "description": "An exact decimal number as text." }, { "type": "null" } ], "description": "Its change over `window` in percent, or null when there is too little history." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the figure was read." } }, "required": [ "subject", "label", "unit", "value", "window", "changePct", "asOf" ], "description": "A market figure, as it reads now." }, "MarketNewsMove": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9]\\d{0,18}$", "description": "The move's id; newer moves have larger ids." }, "kind": { "type": "string", "enum": [ "price", "market", "odds", "resolved", "volume", "share", "leader", "entrant" ], "description": "What kind of move it is." }, "text": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The move in one plain sentence: `WIF up 18.4% in 4 hours`." }, "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin spotted it." }, "subjects": { "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/MarketNewsSubject" }, "description": "What moved, first the subject the sentence is about." }, "changePct": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$", "description": "An exact decimal number as text." }, { "type": "null" } ], "description": "The move's size in percent, for a price, market or volume move; null for the rest." }, "changePoints": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$", "description": "An exact decimal number as text." }, { "type": "null" } ], "description": "The move's size in percentage points, for odds and shares; null for the rest." }, "window": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ], "description": "The window the move happened over, when it has one: `15m`, `4h`, `7d`." } }, "required": [ "id", "kind", "text", "at", "subjects", "changePct", "changePoints", "window" ], "description": "A move in the market, as Fin spotted it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInputForRegistration": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # List market headlines 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. `GET /v1/market/headlines` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$" }, "in": "query", "name": "subject", "required": false, "description": "Only articles naming this coin or stock, of the newest 300: `asset:btc`, `stock:NVDA`." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/market/headlines' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 A page of articles. ```json { "description": "A page of articles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketHeadlines" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "market.headlines.list", "summary": "List market headlines", "tags": [ "market" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$" }, "in": "query", "name": "subject", "required": false, "description": "Only articles naming this coin or stock, of the newest 300: `asset:btc`, `stock:NVDA`." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "A page of articles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketHeadlines" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "MarketHeadlines": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketHeadline" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ], "description": "Articles from reviewed publishers, newest first." }, "MarketHeadline": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The article's id." }, "publisher": { "type": "string", "minLength": 1, "maxLength": 253, "description": "Who published it, as their web domain." }, "headline": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Its headline." }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Where to read it." }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When it was published, when the publisher says." }, "excerpt": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ], "description": "A short excerpt, where the publisher's licence allows one." }, "subjects": { "maxItems": 8, "type": "array", "items": { "$ref": "#/components/schemas/MarketNewsSubject" }, "description": "The coins and stocks its headline names, in the order it names them." } }, "required": [ "id", "publisher", "headline", "url", "publishedAt", "excerpt", "subjects" ], "description": "An article, with what it is about." }, "MarketNewsSubject": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$", "description": "What the subject is, as `kind:id`: `asset:btc`, `stock:NVDA`, `prediction:`, `chain:solana`, or `market` for the whole crypto market." }, "kind": { "type": "string", "enum": [ "market", "chain", "asset", "stock", "launchpad", "venue", "pool", "instrument", "fund", "sector", "indicator", "prediction", "account", "publisher", "narrative" ], "description": "What kind of subject it is: `asset` (a coin), `stock`, `prediction` (a prediction market), `chain`, `market`, or a `launchpad`, `venue`, `sector` and the like." }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Its name; for a prediction market, its question." }, "symbol": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "description": "Its ticker or symbol, when it has one." }, "coingeckoId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Its CoinGecko listing, when it has one, by its kind: a coin's (`bitcoin`, `pump-fun`), an exchange's for a venue (`binance`), a category's for a sector (`layer-1`). What its price history and its logo are found by." }, "hyperliquidCoin": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ], "description": "The coin its Hyperliquid market trades as (`BTC`, `PUMP`), when it has one." }, "defillamaId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Its DefiLlama listing, when it has one: a protocol's slug for a venue or launchpad (`uniswap-v3`, `pump.fun`), a chain's name for a chain (`Ethereum`). What its logo is found by." } }, "required": [ "id", "kind", "name", "symbol", "coingeckoId", "hyperliquidCoin", "defillamaId" ], "description": "Something the news is about." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # List market moves 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 /v1/market/moves` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$" }, "in": "query", "name": "subject", "required": false, "description": "Only moves on this subject." }, { "schema": { "type": "string", "enum": [ "price", "market", "odds", "resolved", "volume", "share", "leader", "entrant" ] }, "in": "query", "name": "kind", "required": false, "description": "Only moves of this kind." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/market/moves' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 A page of moves. ```json { "description": "A page of moves.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketMoves" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "market.moves.list", "summary": "List market moves", "tags": [ "market" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$" }, "in": "query", "name": "subject", "required": false, "description": "Only moves on this subject." }, { "schema": { "type": "string", "enum": [ "price", "market", "odds", "resolved", "volume", "share", "leader", "entrant" ] }, "in": "query", "name": "kind", "required": false, "description": "Only moves of this kind." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "A page of moves.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketMoves" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "MarketMoves": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketNewsMove" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "description": "How many rows the list holds in all, when it is known.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "data", "nextCursor" ], "description": "Moves Fin spotted in the market, newest first." }, "MarketNewsMove": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9]\\d{0,18}$", "description": "The move's id; newer moves have larger ids." }, "kind": { "type": "string", "enum": [ "price", "market", "odds", "resolved", "volume", "share", "leader", "entrant" ], "description": "What kind of move it is." }, "text": { "type": "string", "minLength": 1, "maxLength": 300, "description": "The move in one plain sentence: `WIF up 18.4% in 4 hours`." }, "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When Fin spotted it." }, "subjects": { "maxItems": 20, "type": "array", "items": { "$ref": "#/components/schemas/MarketNewsSubject" }, "description": "What moved, first the subject the sentence is about." }, "changePct": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$", "description": "An exact decimal number as text." }, { "type": "null" } ], "description": "The move's size in percent, for a price, market or volume move; null for the rest." }, "changePoints": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$", "description": "An exact decimal number as text." }, { "type": "null" } ], "description": "The move's size in percentage points, for odds and shares; null for the rest." }, "window": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ], "description": "The window the move happened over, when it has one: `15m`, `4h`, `7d`." } }, "required": [ "id", "kind", "text", "at", "subjects", "changePct", "changePoints", "window" ], "description": "A move in the market, as Fin spotted it." }, "MarketNewsSubject": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 240, "pattern": "^(market|[a-z_]+:[^\\s]+)$", "description": "What the subject is, as `kind:id`: `asset:btc`, `stock:NVDA`, `prediction:`, `chain:solana`, or `market` for the whole crypto market." }, "kind": { "type": "string", "enum": [ "market", "chain", "asset", "stock", "launchpad", "venue", "pool", "instrument", "fund", "sector", "indicator", "prediction", "account", "publisher", "narrative" ], "description": "What kind of subject it is: `asset` (a coin), `stock`, `prediction` (a prediction market), `chain`, `market`, or a `launchpad`, `venue`, `sector` and the like." }, "name": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Its name; for a prediction market, its question." }, "symbol": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "description": "Its ticker or symbol, when it has one." }, "coingeckoId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Its CoinGecko listing, when it has one, by its kind: a coin's (`bitcoin`, `pump-fun`), an exchange's for a venue (`binance`), a category's for a sector (`layer-1`). What its price history and its logo are found by." }, "hyperliquidCoin": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ], "description": "The coin its Hyperliquid market trades as (`BTC`, `PUMP`), when it has one." }, "defillamaId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Its DefiLlama listing, when it has one: a protocol's slug for a venue or launchpad (`uniswap-v3`, `pump.fun`), a chain's name for a chain (`Ethereum`). What its logo is found by." } }, "required": [ "id", "kind", "name", "symbol", "coingeckoId", "hyperliquidCoin", "defillamaId" ], "description": "Something the news is about." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # Get market flows 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. `GET /v1/market/flows` ## Authentication All credentials below are required. - Header: `X-Api-Key: YOUR_API_KEY` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/market/flows' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## Responses ### 200 The market's money flows. ```json { "description": "The market's money flows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketFlows" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "market.flows.get", "summary": "Get market flows", "tags": [ "market" ], "description": "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.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The market's money flows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketFlows" } } } }, "400": { "$ref": "#/components/responses/InvalidInputForRegistration" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenForRegistration" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "parameters": [] }, "components": { "schemas": { "MarketFlows": { "type": "object", "properties": { "data": { "maxItems": 6, "type": "array", "items": { "$ref": "#/components/schemas/MarketFlow" }, "description": "Each figure Fin has now." } }, "required": [ "data" ], "description": "Where money is in the crypto market and how it moved over a day, a week and a month." }, "MarketFlow": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "market_cap", "alt_volume", "perps_open_interest", "stablecoin_supply", "dex_volume", "launchpad_volume" ], "description": "Which figure it is." }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The figure in plain words." }, "valueUsd": { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$", "description": "The figure in US dollars: a level for market cap, open interest and stablecoin supply; the latest day's total for a volume." }, "changes": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "window": { "type": "string", "enum": [ "1d", "7d", "30d" ], "description": "The window." }, "changePct": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$", "description": "An exact decimal number as text." }, { "type": "null" } ], "description": "The change over the window in percent, against the window before for a volume; null when there is too little history." } }, "required": [ "window", "changePct" ] }, "description": "Its change over each window, shortest first." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the figure was read." } }, "required": [ "key", "label", "valueUsd", "changes", "asOf" ], "description": "Where money is in the crypto market, and how it moved." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInputForRegistration": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ForbiddenForRegistration": { "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } } } } ``` --- # List automation data sources Lists what an automation can watch (for example prices or incoming webhooks), the settings each takes, and whether this user can use it. `GET /v1/users/{userId}/automation-sources` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/automation-sources' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The data sources an automation can watch. ```json { "description": "The data sources an automation can watch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationSource" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.listSources", "summary": "List automation data sources", "tags": [ "automations" ], "description": "Lists what an automation can watch (for example prices or incoming webhooks), the settings each takes, and whether this user can use it.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The data sources an automation can watch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationSource" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "AutomationSource": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The operation's id within the catalog." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The operation's version." }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "A short display name for this source." }, "description": { "type": "string", "maxLength": 2048, "description": "What this source reads, in the catalog's own words." }, "semanticIdentity": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "What this operation actually reads, independent of its exact configuration; used to tell equivalent sources apart." }, "schemaFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of this operation's exact configuration and result field types, derived from the registry." }, "configSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object", "description": "Always `object`: a source's configuration is a flat set of named fields." }, "properties": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "additionalProperties": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "string", "description": "A text value." }, "enum": { "description": "The exact values allowed, when this field is closed to a fixed list.", "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, "minLength": { "description": "The shortest allowed length, in characters.", "type": "integer", "minimum": 0, "maximum": 4096 }, "maxLength": { "description": "The longest allowed length, in characters.", "type": "integer", "minimum": 0, "maximum": 4096 }, "pattern": { "description": "A regular expression this field's value must match, when its shape is constrained.", "type": "string", "maxLength": 1024 }, "default": { "description": "The value used when this field is left unset.", "type": "string", "maxLength": 4096 } }, "required": [ "type" ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "boolean", "description": "A true/false value." }, "default": { "description": "The value used when this field is left unset.", "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "integer", "description": "A whole-number value." }, "minimum": { "description": "The smallest allowed value.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maximum": { "description": "The largest allowed value.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enum": { "description": "The exact values allowed, when this field is closed to a fixed list.", "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "default": { "description": "The value used when this field is left unset.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "type" ] } ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "array", "description": "A list of scalar values." }, "items": { "oneOf": [ { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "string", "description": "A text value." }, "enum": { "description": "The exact values allowed, when this field is closed to a fixed list.", "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, "minLength": { "description": "The shortest allowed length, in characters.", "type": "integer", "minimum": 0, "maximum": 4096 }, "maxLength": { "description": "The longest allowed length, in characters.", "type": "integer", "minimum": 0, "maximum": 4096 }, "pattern": { "description": "A regular expression this field's value must match, when its shape is constrained.", "type": "string", "maxLength": 1024 }, "default": { "description": "The value used when this field is left unset.", "type": "string", "maxLength": 4096 } }, "required": [ "type" ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "boolean", "description": "A true/false value." }, "default": { "description": "The value used when this field is left unset.", "type": "boolean" } }, "required": [ "type" ] }, { "type": "object", "properties": { "title": { "description": "A short label for this configuration field, for display.", "type": "string", "maxLength": 120 }, "description": { "description": "Help text for this configuration field, for display.", "type": "string", "maxLength": 2048 }, "type": { "type": "string", "const": "integer", "description": "A whole-number value." }, "minimum": { "description": "The smallest allowed value.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maximum": { "description": "The largest allowed value.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enum": { "description": "The exact values allowed, when this field is closed to a fixed list.", "minItems": 1, "maxItems": 128, "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "default": { "description": "The value used when this field is left unset.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "type" ] } ], "description": "The type each item in the list must match." }, "minItems": { "description": "The fewest items allowed.", "type": "integer", "minimum": 0, "maximum": 64 }, "maxItems": { "description": "The most items allowed.", "type": "integer", "minimum": 0, "maximum": 64 } }, "required": [ "type", "items" ] } ] }, "description": "Each configuration field this source accepts, keyed by field name." }, "required": { "default": [], "description": "Which configuration fields must be set.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" } }, "additionalProperties": { "type": "boolean", "const": false, "description": "Always `false`: no configuration field outside `properties` is accepted." } }, "required": [ "type", "properties", "required", "additionalProperties" ], "description": "This source's configuration, as a bounded JSON Schema subset the generic source editor can render." }, "fields": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields this source's observations carry." }, "public": { "type": "boolean", "description": "Whether this source reads data anyone can read, rather than data scoped to the owner's own connection." }, "requiredConnectionScopes": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The connection scopes a binding needs before this source is available, when it needs any." }, "supportedSubjects": { "type": "object", "properties": { "subjects": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The subjects this source can be configured to read, when it is bounded to a known list." }, "assets": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The assets this source can be configured to read, when it is bounded to a known list." }, "networks": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The networks this source can be configured to read, when it is bounded to a known list." }, "filters": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The other filters this source accepts, when it is bounded to a known list." } }, "required": [ "subjects", "assets", "networks", "filters" ], "description": "What this source can be configured to read, where the catalog knows the bounds; empty where any value is accepted." }, "guarantees": { "type": "object", "properties": { "delivery": { "description": "Push delivery; absent means polling.", "type": "string", "const": "push" }, "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "presentation": { "type": "object", "properties": { "subjectConfigKey": { "description": "Which configuration field names the subject being watched, when the editor should highlight one.", "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "fields": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "A short display label for this field." }, "meaning": { "description": "One plain sentence on what the field means, shown to a person beside a condition on it.", "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "path", "label" ] }, "description": "Reviewed display labels for a subset of this source's fields." } }, "required": [ "fields" ], "description": "Reviewed display copy for the source editor: cosmetic only, never part of an execution descriptor or a saved source pin." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "availability": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "needs_connection", "unavailable", "unknown" ], "description": "Whether this source is usable for the current owner: `available` ready to use, `needs_connection` the owner must set something up first (such as their agent wallet), `unknown` availability has not been checked yet, or an earlier check's validity window has expired. `unavailable` marks a shared source this deployment does not offer: an automation that reads it is refused, so use another source." }, "configured": { "type": "boolean", "description": "Whether the owner has set up a connection for this source." }, "verified": { "type": "boolean", "description": "Whether that connection has been confirmed to work." }, "grantedScopes": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "The connection scopes the owner has actually granted." }, "checkedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When availability was last checked, when it has been." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this availability check expires and must be re-checked, when it has an expiry." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "description": "Why this source is not available, when it is not." } }, "required": [ "status", "configured", "verified", "grantedScopes", "checkedAt", "expiresAt", "reason" ], "description": "This owner's ability to use this source right now: whether it is connected and verified. Carries no credential, account or provider connection identifier." } }, "required": [ "id", "version", "label", "description", "semanticIdentity", "schemaFingerprint", "configSchema", "fields", "public", "requiredConnectionScopes", "supportedSubjects", "guarantees", "availability" ], "description": "One event source an automation may watch: its configuration schema, its data fields, and this owner's current ability to use it." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List automations 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 /v1/users/{userId}/automations` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "default": "all", "type": "string", "enum": [ "all", "current", "enabled", "paused", "deleted" ] }, "in": "query", "name": "filter", "required": false, "description": "Which automations to list: `all` every one, `current` every one not deleted, `enabled` active ones, `paused` paused ones, `deleted` deleted ones." }, { "schema": { "type": "string", "maxLength": 120 }, "in": "query", "name": "query", "required": false, "description": "Distinctive search words, not the whole user request. Every word must match a whole token in the name, instructions or reviewed rule description; matching is case-insensitive. Omit to browse." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/automations' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The user's automations. ```json { "description": "The user's automations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.list", "summary": "List automations", "tags": [ "automations" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "default": "all", "type": "string", "enum": [ "all", "current", "enabled", "paused", "deleted" ] }, "in": "query", "name": "filter", "required": false, "description": "Which automations to list: `all` every one, `current` every one not deleted, `enabled` active ones, `paused` paused ones, `deleted` deleted ones." }, { "schema": { "type": "string", "maxLength": 120 }, "in": "query", "name": "query", "required": false, "description": "Distinctive search words, not the whole user request. Every word must match a whole token in the name, instructions or reviewed rule description; matching is case-insensitive. Omit to browse." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The user's automations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "description": "The saved revision number. Use it to ignore older cached reads after chat edits. This server always returns it; earlier servers may omit it.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "description": "The automation's name." }, "prompt": { "type": "string", "description": "The instructions given to the model each time this automation fires." }, "rule": { "$ref": "#/components/schemas/AutomationRule" }, "missedRun": { "type": "string", "enum": [ "skip", "ask" ], "description": "What happens to a run that can't go through before its deadline: `skip` counts it and keeps the schedule, `ask` pauses the automation until its owner decides. A failure only the owner can fix pauses either way." }, "summary": { "type": "string", "description": "When the automation runs, in one readable sentence or two: its condition, then its schedule and run limit. Times are in UTC unless the schedule names its own time zone." }, "sourcePlans": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "result": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "ready", "description": "The binding is fully planned and ready to collect." }, "plan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "delivery": { "description": "Push delivery; absent means polling.", "type": "string", "const": "push" }, "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "How one binding will actually be collected: the operation, its guarantees and its configuration." } }, "required": [ "status", "plan" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "needs_connection", "description": "The binding is plannable but needs a connection the owner has not granted yet." }, "candidatePlan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "delivery": { "description": "Push delivery; absent means polling.", "type": "string", "const": "push" }, "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "The plan that would apply once the missing connection is granted." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "candidatePlan", "reasons" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unsupported", "description": "The binding cannot be planned at all, as asked." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "reasons" ] } ], "description": "Whether this binding is ready, needs a connection, or is unsupported, and why." } }, "required": [ "binding", "result" ] }, "description": "How each of the rule's bindings will actually be collected." }, "enabled": { "type": "boolean", "description": "Whether this automation is active: false while it is paused and once deleted." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation was last changed." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the automation was deleted; null while it exists." }, "hold": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the hold began." }, "reason": { "description": "Why an operator placed the hold, when they gave one.", "type": [ "string", "null" ] } }, "required": [ "at", "reason" ] }, { "type": "null" } ], "description": "An operator's hold: why future work is stopped, so the owner does not read it as their own doing." }, "waitingForOwner": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "add_funds", "edit_automation", "decide", "resume" ], "description": "What it needs: `add_funds`, `edit_automation`, `decide` whether to act now or keep it as it is, or `resume`: it can no longer read the data it watches until the owner resumes it, which reads that data afresh." }, "reason": { "type": "string", "description": "Why it stopped, one of the reasons a run gives: see `reason` on the automation run. A `resume` gives `unavailable`." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The automation run it paused over, or null for a `resume`, which no run caused." }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it paused." } }, "required": [ "action", "reason", "runId", "since" ] }, { "type": "null" } ], "description": "When fin paused this automation because only the owner can move it on: what it needs, and the run it stopped at when a run caused it. Null otherwise, including while the owner paused it themselves. Resuming clears it." }, "runCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many numbered runs it has had, the number its latest numbered run's `runNumber` reached. Exits and skipped checks are not counted." }, "skippedRunCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many of its runs were skipped: each failed, counted toward the run limit, and left the schedule as it was. A run it paused over is not one of them." }, "harvestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times it has taken a gain: harvest runs that settled at least in part. A run that failed, is uncertain or found nothing to trade isn't counted. Zero for an automation that doesn't harvest." }, "nextFireAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation's clock will next wake it, when it has a schedule and is enabled." }, "monitoring": { "$ref": "#/components/schemas/AutomationMonitoring" }, "activeRun": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRun" }, { "type": "null" } ], "description": "The automation run in progress or waiting to start, when there is one." }, "latestRun": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRun" }, { "type": "null" } ], "description": "The most recent automation run, finished or not, when there has been one." }, "contract": { "anyOf": [ { "type": "object", "properties": { "terms": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "oneOf": [ { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" } ], "description": "A standing Solana grant: an exact buy, or a sale of a fraction of the holding for USDC, made exactly as approved each time the automation fires." } ], "description": "The approved contract's exact terms." }, "approvedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the owner approved this contract." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this contract was withdrawn, when it has been." }, "executionsUsed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Executions that consumed the allowance. For a transfer contract, entry plans from the plan and leg ledger: an exit plan is exempt and never counted. For a perps automation, the firings whose exact order or funding was submitted. For a Solana grant, the firings whose trade or funding got past its first claim to sign." }, "spendUsed": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "description": "A capped input token of the approved contract." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "That token's decimals, copied from the approved cap." }, "spentRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the grant has spent of that token, raw. Claimed, signed, uncertain, settled and not-executed legs count, because a not-executed ending can follow a consumed deposit; only a refunded leg releases its part. The policy worker enforces the cap too and counts every debit it signed, refunded or not, so after a refund the room it grants can be smaller than this figure suggests." } }, "required": [ "tokenId", "decimals", "spentRaw" ] }, "description": "One entry for each capped input token, in the contract's order; empty when the contract has no total cap. The cap itself is terms.maxTotalInput, so the cap minus this is the most that is left: the policy worker, which signs, counts every debit it signed, refunded or not." }, "settledSpend": { "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "description": "A capped input token of the approved contract." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "That token's decimals, copied from the approved cap." }, "spentRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What has settled of that token, raw. Only settled legs count: nothing in flight, uncertain or not executed. A refunded leg counts nothing, a partly refunded one included, even though part of it may have been spent." } }, "required": [ "tokenId", "decimals", "spentRaw" ] }, "description": "What has actually settled of each capped input token, in the same shape as `spendUsed`: show this as what the automation spent, and `spendUsed` for what room is left. Unlike `spendUsed` it leaves out legs still in flight, uncertain, not executed or refunded. An edited grant's figure includes what it carried over, which can hold a not-executed debit from before the edit." } }, "required": [ "terms", "approvedAt", "revokedAt", "executionsUsed", "spendUsed", "settledSpend" ] }, { "type": "null" } ], "description": "The standing financial authority this automation's engine-fired runs execute under; null for an automation without one." } }, "required": [ "id", "name", "prompt", "rule", "missedRun", "summary", "sourcePlans", "enabled", "createdAt", "updatedAt", "deletedAt", "hold", "waitingForOwner", "runCount", "skippedRunCount", "harvestCount", "nextFireAt", "monitoring", "activeRun", "latestRun", "contract" ], "description": "One automation: its rule and a readable summary of it, its current sources, its monitoring health, and its runs." }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ] } }, "required": [ "intervalSeconds", "readers" ] }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ] }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "AutomationMonitoring": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable", "paused", "completed" ], "description": "The automation's overall monitoring status: `waiting` no evaluation yet, `healthy` sources and evaluation are current, `stale` an input is older than expected, `unavailable` a source could not be reached, `paused` firing is paused, `completed` its run policy is spent. A news exit (`rule.news`) reads `healthy` while Fin's news judge checks the news for it and `unavailable` while news checks are paused for its owner." }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When monitoring last checked this automation's sources." }, "sources": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "description": "The source's id within its provider." }, "check": { "description": "The most recent recipe check against this source, when evidence review is configured.", "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ] }, "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable" ], "description": "This source's health: `waiting` no observation yet, `healthy` fresh, `stale` older than expected, `unavailable` the provider could not be reached." }, "sourceTime": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the provider says the most recent observation was true." }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the engine received the most recent observation." }, "reason": { "description": "Why the source is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "binding", "sourceId", "status", "sourceTime", "receivedAt", "reason" ] }, "description": "Each bound source's own health." }, "lastEvaluation": { "anyOf": [ { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "true", "false", "unknown" ], "description": "Whether the condition holds: `true` it matches, `false` it does not, `unknown` usable input is missing. Firing policy, delivery, admission, budget and approvals separately decide whether matching can execute." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this evaluation ran." }, "reasons": { "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "nodePath": { "maxItems": 8, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "The path to the condition node this reason explains, as indices into the rule tree." }, "code": { "type": "string", "enum": [ "missing_source", "unavailable", "gap", "stale", "future", "missing_field", "invalid_value", "snapshot_skew" ], "description": "Why this node could not cleanly resolve: `missing_source` no binding was configured, `unavailable` the provider did not answer, `gap` a break in coverage was recorded, `stale` or `future` a timestamp was out of range, `missing_field` the observation lacked this field, `invalid_value` the value did not match its declared type, `snapshot_skew` the inputs disagreed on when they were true." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "nodePath", "code" ] }, "description": "Why the verdict is what it is, one entry per condition node that did not cleanly resolve." }, "inputs": { "maxItems": 5, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "snapshot", "description": "A point-in-time read of current state." }, "sourceTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the provider says this snapshot was true." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime" ] }, { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "received_event", "description": "An event the source pushed, or the engine collected as it happened." }, "sourceTime": { "type": "null", "description": "Not applicable to a received event; see `occurredAt` and `providerPublishedAt` instead." }, "providerPublishedAt": { "anyOf": [ { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When the provider says it published this event, when it reports one." }, "occurredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the event actually happened, when the provider reports that separately from when it was published." }, "finalizedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the provider considers this event no longer subject to correction, when it reports one." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime", "providerPublishedAt", "occurredAt", "finalizedAt" ] } ] }, "description": "Each input this evaluation read, without its raw data." } }, "required": [ "verdict", "evaluatedAt", "reasons", "inputs" ] }, { "type": "null" } ], "description": "The rule's most recent evaluation, when it has run at least once." }, "webhook": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether a webhook secret has been minted." }, "keyId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The current webhook secret's id, for rotation." }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the webhook last received a request." } }, "required": [ "configured", "keyId", "lastReceivedAt" ] }, { "type": "null" } ], "description": "This automation's owner webhook, when its rule has one; null for a news exit." }, "reason": { "description": "Why status is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "status", "lastCheckedAt", "sources", "lastEvaluation", "webhook", "reason" ], "description": "An automation's current health: its sources, its most recent evaluation, and its inbound webhook, if it has one." }, "AutomationRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run's id." }, "deliverySequence": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "This automation run's place in delivery order across all automations, as a string so it sorts and compares exactly at any size. A paging cursor, not a count of this automation's runs: `runNumber` is that." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The automation definition version this automation run was recorded under." }, "activationEpoch": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The activation epoch this automation run was recorded under." }, "name": { "type": "string", "description": "The automation's name when this automation run was recorded." }, "prompt": { "type": "string", "description": "The automation's prompt when this automation run was recorded." }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "decision", "external" ], "description": "What produced this automation run: `decision` the rule's own condition, `external` a source that decided on the engine's behalf." }, "identity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A stable string identifying this exact decision, used to deduplicate exact replays within one activation. Reuse with changed data conflicts." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this decision was made." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "The observations behind one decision, exactly as evaluated. Bounded to 256 KiB, 24 levels of nesting and 16384 entries." }, "sourceChecks": { "description": "Recipe checks recorded for each source this decision read, when evidence review is configured.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding this check was collected for." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The specific event or observation this check backs." }, "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this check ran." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "check": { "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ], "description": "A recorded run of a recipe's steps against the real source, kept as evidence." } }, "required": [ "binding", "sourceId", "eventId", "operationId", "operationVersion", "check" ], "description": "Frozen recipe evidence tied to the actual observation used by one decision." } } }, "required": [ "kind", "identity", "evaluatedAt", "data" ], "description": "Why this automation run happened: the decision, its evaluated data, and any recipe checks behind it." }, "selection": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "entry", "description": "This firing runs every entry action of the contract, in order." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exit", "description": "This firing runs exactly one exit action." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the approved exit action this firing selected." }, "exitKind": { "type": "string", "enum": [ "take_profit", "stop_loss", "harvest_every" ], "description": "Which guard fired: a take-profit, a stop-loss or a scheduled harvest." } }, "required": [ "kind", "actionIndex", "exitKind" ] } ], "description": "What this automation run's firing selected out of its contract: every entry action in order (`Scheduled buy`), or exactly one exit action (`Take-profit exit`/`Stop-loss exit`). A definition without a contract records `{ kind: \"entry\" }`." }, "state": { "type": "string", "enum": [ "pending", "deferred", "accepted", "retrying", "succeeded", "partial", "failed", "uncertain", "rejected", "canceled", "skipped", "coalesced" ], "description": "This automation run's state: `pending` waiting to start, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to an agent run, `retrying` waiting to try again before its deadline, `succeeded` it did what it was asked, `partial` only some of it went through, `failed` it moved nothing it was asked to, `uncertain` money may have moved and how it ended is not known yet, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before starting, `skipped` an earlier automation run was still active or it was missed, `coalesced` merged into a newer match." }, "reason": { "description": "Why the automation run is in this state, when there is one to give. A run that failed or went through only in part gives one of `unavailable`, `insufficient_funds`, `quote_rejected`, `not_authorized`, `not_executed` or `condition_passed`.", "type": [ "string", "null" ] }, "runNumber": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Which of its automation's runs this is, counting from 1, the number its run limit counts. Null for a run that is no scheduled or triggered firing of its own, such as an exit check selling a position. Show this, not `deliverySequence`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation run was recorded." }, "deliveryDeadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest this automation run could still start." }, "deadlineAt": { "description": "The latest this run may still try, once it has started: the earliest of its delivery deadline, the windows its owner signed and its next firing. Null or absent for a run that never started, or one from before this field. Use it, not `deliveryDeadline`, to say how long a run had.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "nextAttemptAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the next attempt to start this automation run is due." }, "lastAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation run was last tried, when it has been." }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many attempts to start this automation run there have been." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation this automation run works in, once it has one." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The agent run this automation run started, once it has one." }, "runStatus": { "anyOf": [ { "type": "string", "enum": [ "running", "paused", "completed", "failed", "aborted" ] }, { "type": "null" } ], "description": "That agent run's status, once it has one: `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "runError": { "description": "Why the agent run failed, when it did.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals this automation run's agent run is waiting on." }, "solana": { "description": "For a Solana trading automation, the admitted trade and its observed result. Absent or null before it acts and for other automations. Read this result independently of runStatus.", "anyOf": [ { "$ref": "#/components/schemas/AutomationRunSolana" }, { "type": "null" } ] }, "perps": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRunPerps" }, { "type": "null" } ], "description": "For a perps automation, the order this run placed or the margin it added, with Hyperliquid's answer. Null for any other automation, and until the run acts." } }, "required": [ "id", "deliverySequence", "automationId", "definitionVersion", "activationEpoch", "name", "prompt", "evidence", "selection", "state", "reason", "runNumber", "createdAt", "deliveryDeadline", "nextAttemptAt", "lastAttemptAt", "attempts", "conversationId", "runId", "runStatus", "runError", "pendingApprovals", "perps" ], "description": "One time an automation ran or was due to run: why, its delivery state, and the agent run it started, if any." }, "AutomationRunSolana": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "buy" }, "request": { "$ref": "#/components/schemas/SolanaBuyInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; an agent run completing does not prove that money moved." } }, "required": [ "id", "kind", "request", "outcome" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "sell" }, "request": { "$ref": "#/components/schemas/SolanaSellInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; a partial result may leave SOL in the Solana account." } }, "required": [ "id", "kind", "request", "outcome" ] } ], "description": "The Solana trade this automation run admitted, with its observed financial result." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "AutomationRunPerps": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "order", "description": "A reduce-only order on the automation's position." }, "order": { "description": "The exact order the run placed: the coin, side, size and worst price (`entry.price`) this firing allowed.", "$ref": "#/components/schemas/PerpsOrderInput" }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/PerpsOrderOutcome" }, { "type": "null" } ], "description": "Hyperliquid's answer, with each placement's fill. Null while the order is being sent or its answer is still being checked; the run never sends it twice." } }, "required": [ "kind", "order", "outcome" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "margin", "description": "Margin moved from the agent wallet to the perps account." }, "transfer": { "description": "The exact USDC amount the run moved, in six-decimal units, and its loss bound.", "$ref": "#/components/schemas/PerpsTransferInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "How the transfer ended. Null while it is still under way." } }, "required": [ "kind", "transfer", "outcome" ] } ], "description": "What one run of a perps automation did on Hyperliquid: the reduce-only order it placed or the margin it added, with the answer it got." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsOrderOutcome": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "placed", "rejected", "uncertain", "cancelled", "applied", "not_executed" ], "description": "`placed` Hyperliquid accepted the order (see each placement), `rejected` it accepted none (or refused the margin change), `uncertain` the answer was lost and the host reconciles what is still unknown by client order id (a trailing stop with no answer only when one order matches its terms; a margin change from the account's own transaction list), `cancelled` the cancellation took effect, `applied` the margin change took effect, `not_executed` nothing was signed." }, "placements": { "maxItems": 4, "type": "array", "items": { "$ref": "#/components/schemas/PerpsPlacementOutcome" }, "description": "Each placement's own answer, in the order's order: entry, take-profit, stop-loss, then trailing stop." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why nothing was placed or the cancellation did not take effect, in Hyperliquid's or the host's words; null otherwise." } }, "required": [ "status", "placements", "reason" ], "description": "The result of one approved perps order, cancellation or margin change." }, "PerpsPlacementOutcome": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "entry", "take_profit", "stop_loss", "trailing_stop" ], "description": "Which part of the order: `entry`, `take_profit`, `stop_loss` or `trailing_stop`." }, "cloid": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-f]{32}$" }, { "type": "null" } ], "description": "The client order id it is reconciled by; null for a trailing stop, which Hyperliquid gives none and the host matches by its terms instead." }, "state": { "type": "string", "enum": [ "filled", "resting", "triggered_pending", "triggered", "cancelled", "rejected", "unknown" ], "description": "`filled` executed (possibly partly; see `filledSize`), `resting` waits on the book, `triggered_pending` is an exit waiting for its trigger, `triggered` is an exit whose trigger fired and became a market order (its fill is in the account's fills, not here), `rejected` never placed, `unknown` not yet known: never resubmit it." }, "oid": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Hyperliquid's order id once it named one; null for a trigger it answered without one, or an answer not yet known." }, "filledSize": { "description": "How much filled, in the coin, as Hyperliquid wrote it; null when nothing filled or it did not say.", "type": [ "string", "null" ] }, "averagePrice": { "description": "The average fill price, as Hyperliquid wrote it; null when it did not say.", "type": [ "string", "null" ] }, "error": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Hyperliquid's own refusal text for this placement; null otherwise." } }, "required": [ "role", "cloid", "state", "oid", "filledSize", "averagePrice", "error" ], "description": "What one placement of an order came to on Hyperliquid." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get an automation Returns an automation: its name, its instructions, a readable `summary` of when it runs, its status and its latest run. `GET /v1/users/{userId}/automations/{automationId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The automation. ```json { "description": "The automation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.get", "summary": "Get an automation", "tags": [ "automations" ], "description": "Returns an automation: its name, its instructions, a readable `summary` of when it runs, its status and its latest run.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "description": "The saved revision number. Use it to ignore older cached reads after chat edits. This server always returns it; earlier servers may omit it.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "description": "The automation's name." }, "prompt": { "type": "string", "description": "The instructions given to the model each time this automation fires." }, "rule": { "$ref": "#/components/schemas/AutomationRule" }, "missedRun": { "type": "string", "enum": [ "skip", "ask" ], "description": "What happens to a run that can't go through before its deadline: `skip` counts it and keeps the schedule, `ask` pauses the automation until its owner decides. A failure only the owner can fix pauses either way." }, "summary": { "type": "string", "description": "When the automation runs, in one readable sentence or two: its condition, then its schedule and run limit. Times are in UTC unless the schedule names its own time zone." }, "sourcePlans": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "result": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "ready", "description": "The binding is fully planned and ready to collect." }, "plan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "delivery": { "description": "Push delivery; absent means polling.", "type": "string", "const": "push" }, "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "How one binding will actually be collected: the operation, its guarantees and its configuration." } }, "required": [ "status", "plan" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "needs_connection", "description": "The binding is plannable but needs a connection the owner has not granted yet." }, "candidatePlan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "delivery": { "description": "Push delivery; absent means polling.", "type": "string", "const": "push" }, "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "The plan that would apply once the missing connection is granted." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "candidatePlan", "reasons" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unsupported", "description": "The binding cannot be planned at all, as asked." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "reasons" ] } ], "description": "Whether this binding is ready, needs a connection, or is unsupported, and why." } }, "required": [ "binding", "result" ] }, "description": "How each of the rule's bindings will actually be collected." }, "enabled": { "type": "boolean", "description": "Whether this automation is active: false while it is paused and once deleted." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation was last changed." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the automation was deleted; null while it exists." }, "hold": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the hold began." }, "reason": { "description": "Why an operator placed the hold, when they gave one.", "type": [ "string", "null" ] } }, "required": [ "at", "reason" ] }, { "type": "null" } ], "description": "An operator's hold: why future work is stopped, so the owner does not read it as their own doing." }, "waitingForOwner": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "add_funds", "edit_automation", "decide", "resume" ], "description": "What it needs: `add_funds`, `edit_automation`, `decide` whether to act now or keep it as it is, or `resume`: it can no longer read the data it watches until the owner resumes it, which reads that data afresh." }, "reason": { "type": "string", "description": "Why it stopped, one of the reasons a run gives: see `reason` on the automation run. A `resume` gives `unavailable`." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The automation run it paused over, or null for a `resume`, which no run caused." }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it paused." } }, "required": [ "action", "reason", "runId", "since" ] }, { "type": "null" } ], "description": "When fin paused this automation because only the owner can move it on: what it needs, and the run it stopped at when a run caused it. Null otherwise, including while the owner paused it themselves. Resuming clears it." }, "runCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many numbered runs it has had, the number its latest numbered run's `runNumber` reached. Exits and skipped checks are not counted." }, "skippedRunCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many of its runs were skipped: each failed, counted toward the run limit, and left the schedule as it was. A run it paused over is not one of them." }, "harvestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times it has taken a gain: harvest runs that settled at least in part. A run that failed, is uncertain or found nothing to trade isn't counted. Zero for an automation that doesn't harvest." }, "nextFireAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation's clock will next wake it, when it has a schedule and is enabled." }, "monitoring": { "$ref": "#/components/schemas/AutomationMonitoring" }, "activeRun": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRun" }, { "type": "null" } ], "description": "The automation run in progress or waiting to start, when there is one." }, "latestRun": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRun" }, { "type": "null" } ], "description": "The most recent automation run, finished or not, when there has been one." }, "contract": { "anyOf": [ { "type": "object", "properties": { "terms": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "oneOf": [ { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" } ], "description": "A standing Solana grant: an exact buy, or a sale of a fraction of the holding for USDC, made exactly as approved each time the automation fires." } ], "description": "The approved contract's exact terms." }, "approvedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the owner approved this contract." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this contract was withdrawn, when it has been." }, "executionsUsed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Executions that consumed the allowance. For a transfer contract, entry plans from the plan and leg ledger: an exit plan is exempt and never counted. For a perps automation, the firings whose exact order or funding was submitted. For a Solana grant, the firings whose trade or funding got past its first claim to sign." }, "spendUsed": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "description": "A capped input token of the approved contract." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "That token's decimals, copied from the approved cap." }, "spentRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the grant has spent of that token, raw. Claimed, signed, uncertain, settled and not-executed legs count, because a not-executed ending can follow a consumed deposit; only a refunded leg releases its part. The policy worker enforces the cap too and counts every debit it signed, refunded or not, so after a refund the room it grants can be smaller than this figure suggests." } }, "required": [ "tokenId", "decimals", "spentRaw" ] }, "description": "One entry for each capped input token, in the contract's order; empty when the contract has no total cap. The cap itself is terms.maxTotalInput, so the cap minus this is the most that is left: the policy worker, which signs, counts every debit it signed, refunded or not." }, "settledSpend": { "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "description": "A capped input token of the approved contract." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "That token's decimals, copied from the approved cap." }, "spentRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What has settled of that token, raw. Only settled legs count: nothing in flight, uncertain or not executed. A refunded leg counts nothing, a partly refunded one included, even though part of it may have been spent." } }, "required": [ "tokenId", "decimals", "spentRaw" ] }, "description": "What has actually settled of each capped input token, in the same shape as `spendUsed`: show this as what the automation spent, and `spendUsed` for what room is left. Unlike `spendUsed` it leaves out legs still in flight, uncertain, not executed or refunded. An edited grant's figure includes what it carried over, which can hold a not-executed debit from before the edit." } }, "required": [ "terms", "approvedAt", "revokedAt", "executionsUsed", "spendUsed", "settledSpend" ] }, { "type": "null" } ], "description": "The standing financial authority this automation's engine-fired runs execute under; null for an automation without one." } }, "required": [ "id", "name", "prompt", "rule", "missedRun", "summary", "sourcePlans", "enabled", "createdAt", "updatedAt", "deletedAt", "hold", "waitingForOwner", "runCount", "skippedRunCount", "harvestCount", "nextFireAt", "monitoring", "activeRun", "latestRun", "contract" ], "description": "One automation: its rule and a readable summary of it, its current sources, its monitoring health, and its runs." }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ] } }, "required": [ "intervalSeconds", "readers" ] }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ] }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "AutomationMonitoring": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable", "paused", "completed" ], "description": "The automation's overall monitoring status: `waiting` no evaluation yet, `healthy` sources and evaluation are current, `stale` an input is older than expected, `unavailable` a source could not be reached, `paused` firing is paused, `completed` its run policy is spent. A news exit (`rule.news`) reads `healthy` while Fin's news judge checks the news for it and `unavailable` while news checks are paused for its owner." }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When monitoring last checked this automation's sources." }, "sources": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "description": "The source's id within its provider." }, "check": { "description": "The most recent recipe check against this source, when evidence review is configured.", "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ] }, "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable" ], "description": "This source's health: `waiting` no observation yet, `healthy` fresh, `stale` older than expected, `unavailable` the provider could not be reached." }, "sourceTime": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the provider says the most recent observation was true." }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the engine received the most recent observation." }, "reason": { "description": "Why the source is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "binding", "sourceId", "status", "sourceTime", "receivedAt", "reason" ] }, "description": "Each bound source's own health." }, "lastEvaluation": { "anyOf": [ { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "true", "false", "unknown" ], "description": "Whether the condition holds: `true` it matches, `false` it does not, `unknown` usable input is missing. Firing policy, delivery, admission, budget and approvals separately decide whether matching can execute." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this evaluation ran." }, "reasons": { "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "nodePath": { "maxItems": 8, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "The path to the condition node this reason explains, as indices into the rule tree." }, "code": { "type": "string", "enum": [ "missing_source", "unavailable", "gap", "stale", "future", "missing_field", "invalid_value", "snapshot_skew" ], "description": "Why this node could not cleanly resolve: `missing_source` no binding was configured, `unavailable` the provider did not answer, `gap` a break in coverage was recorded, `stale` or `future` a timestamp was out of range, `missing_field` the observation lacked this field, `invalid_value` the value did not match its declared type, `snapshot_skew` the inputs disagreed on when they were true." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "nodePath", "code" ] }, "description": "Why the verdict is what it is, one entry per condition node that did not cleanly resolve." }, "inputs": { "maxItems": 5, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "snapshot", "description": "A point-in-time read of current state." }, "sourceTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the provider says this snapshot was true." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime" ] }, { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "received_event", "description": "An event the source pushed, or the engine collected as it happened." }, "sourceTime": { "type": "null", "description": "Not applicable to a received event; see `occurredAt` and `providerPublishedAt` instead." }, "providerPublishedAt": { "anyOf": [ { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When the provider says it published this event, when it reports one." }, "occurredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the event actually happened, when the provider reports that separately from when it was published." }, "finalizedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the provider considers this event no longer subject to correction, when it reports one." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime", "providerPublishedAt", "occurredAt", "finalizedAt" ] } ] }, "description": "Each input this evaluation read, without its raw data." } }, "required": [ "verdict", "evaluatedAt", "reasons", "inputs" ] }, { "type": "null" } ], "description": "The rule's most recent evaluation, when it has run at least once." }, "webhook": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether a webhook secret has been minted." }, "keyId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The current webhook secret's id, for rotation." }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the webhook last received a request." } }, "required": [ "configured", "keyId", "lastReceivedAt" ] }, { "type": "null" } ], "description": "This automation's owner webhook, when its rule has one; null for a news exit." }, "reason": { "description": "Why status is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "status", "lastCheckedAt", "sources", "lastEvaluation", "webhook", "reason" ], "description": "An automation's current health: its sources, its most recent evaluation, and its inbound webhook, if it has one." }, "AutomationRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run's id." }, "deliverySequence": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "This automation run's place in delivery order across all automations, as a string so it sorts and compares exactly at any size. A paging cursor, not a count of this automation's runs: `runNumber` is that." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The automation definition version this automation run was recorded under." }, "activationEpoch": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The activation epoch this automation run was recorded under." }, "name": { "type": "string", "description": "The automation's name when this automation run was recorded." }, "prompt": { "type": "string", "description": "The automation's prompt when this automation run was recorded." }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "decision", "external" ], "description": "What produced this automation run: `decision` the rule's own condition, `external` a source that decided on the engine's behalf." }, "identity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A stable string identifying this exact decision, used to deduplicate exact replays within one activation. Reuse with changed data conflicts." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this decision was made." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "The observations behind one decision, exactly as evaluated. Bounded to 256 KiB, 24 levels of nesting and 16384 entries." }, "sourceChecks": { "description": "Recipe checks recorded for each source this decision read, when evidence review is configured.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding this check was collected for." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The specific event or observation this check backs." }, "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this check ran." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "check": { "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ], "description": "A recorded run of a recipe's steps against the real source, kept as evidence." } }, "required": [ "binding", "sourceId", "eventId", "operationId", "operationVersion", "check" ], "description": "Frozen recipe evidence tied to the actual observation used by one decision." } } }, "required": [ "kind", "identity", "evaluatedAt", "data" ], "description": "Why this automation run happened: the decision, its evaluated data, and any recipe checks behind it." }, "selection": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "entry", "description": "This firing runs every entry action of the contract, in order." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exit", "description": "This firing runs exactly one exit action." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the approved exit action this firing selected." }, "exitKind": { "type": "string", "enum": [ "take_profit", "stop_loss", "harvest_every" ], "description": "Which guard fired: a take-profit, a stop-loss or a scheduled harvest." } }, "required": [ "kind", "actionIndex", "exitKind" ] } ], "description": "What this automation run's firing selected out of its contract: every entry action in order (`Scheduled buy`), or exactly one exit action (`Take-profit exit`/`Stop-loss exit`). A definition without a contract records `{ kind: \"entry\" }`." }, "state": { "type": "string", "enum": [ "pending", "deferred", "accepted", "retrying", "succeeded", "partial", "failed", "uncertain", "rejected", "canceled", "skipped", "coalesced" ], "description": "This automation run's state: `pending` waiting to start, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to an agent run, `retrying` waiting to try again before its deadline, `succeeded` it did what it was asked, `partial` only some of it went through, `failed` it moved nothing it was asked to, `uncertain` money may have moved and how it ended is not known yet, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before starting, `skipped` an earlier automation run was still active or it was missed, `coalesced` merged into a newer match." }, "reason": { "description": "Why the automation run is in this state, when there is one to give. A run that failed or went through only in part gives one of `unavailable`, `insufficient_funds`, `quote_rejected`, `not_authorized`, `not_executed` or `condition_passed`.", "type": [ "string", "null" ] }, "runNumber": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Which of its automation's runs this is, counting from 1, the number its run limit counts. Null for a run that is no scheduled or triggered firing of its own, such as an exit check selling a position. Show this, not `deliverySequence`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation run was recorded." }, "deliveryDeadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest this automation run could still start." }, "deadlineAt": { "description": "The latest this run may still try, once it has started: the earliest of its delivery deadline, the windows its owner signed and its next firing. Null or absent for a run that never started, or one from before this field. Use it, not `deliveryDeadline`, to say how long a run had.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "nextAttemptAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the next attempt to start this automation run is due." }, "lastAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation run was last tried, when it has been." }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many attempts to start this automation run there have been." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation this automation run works in, once it has one." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The agent run this automation run started, once it has one." }, "runStatus": { "anyOf": [ { "type": "string", "enum": [ "running", "paused", "completed", "failed", "aborted" ] }, { "type": "null" } ], "description": "That agent run's status, once it has one: `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "runError": { "description": "Why the agent run failed, when it did.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals this automation run's agent run is waiting on." }, "solana": { "description": "For a Solana trading automation, the admitted trade and its observed result. Absent or null before it acts and for other automations. Read this result independently of runStatus.", "anyOf": [ { "$ref": "#/components/schemas/AutomationRunSolana" }, { "type": "null" } ] }, "perps": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRunPerps" }, { "type": "null" } ], "description": "For a perps automation, the order this run placed or the margin it added, with Hyperliquid's answer. Null for any other automation, and until the run acts." } }, "required": [ "id", "deliverySequence", "automationId", "definitionVersion", "activationEpoch", "name", "prompt", "evidence", "selection", "state", "reason", "runNumber", "createdAt", "deliveryDeadline", "nextAttemptAt", "lastAttemptAt", "attempts", "conversationId", "runId", "runStatus", "runError", "pendingApprovals", "perps" ], "description": "One time an automation ran or was due to run: why, its delivery state, and the agent run it started, if any." }, "AutomationRunSolana": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "buy" }, "request": { "$ref": "#/components/schemas/SolanaBuyInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; an agent run completing does not prove that money moved." } }, "required": [ "id", "kind", "request", "outcome" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "sell" }, "request": { "$ref": "#/components/schemas/SolanaSellInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; a partial result may leave SOL in the Solana account." } }, "required": [ "id", "kind", "request", "outcome" ] } ], "description": "The Solana trade this automation run admitted, with its observed financial result." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "AutomationRunPerps": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "order", "description": "A reduce-only order on the automation's position." }, "order": { "description": "The exact order the run placed: the coin, side, size and worst price (`entry.price`) this firing allowed.", "$ref": "#/components/schemas/PerpsOrderInput" }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/PerpsOrderOutcome" }, { "type": "null" } ], "description": "Hyperliquid's answer, with each placement's fill. Null while the order is being sent or its answer is still being checked; the run never sends it twice." } }, "required": [ "kind", "order", "outcome" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "margin", "description": "Margin moved from the agent wallet to the perps account." }, "transfer": { "description": "The exact USDC amount the run moved, in six-decimal units, and its loss bound.", "$ref": "#/components/schemas/PerpsTransferInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "How the transfer ended. Null while it is still under way." } }, "required": [ "kind", "transfer", "outcome" ] } ], "description": "What one run of a perps automation did on Hyperliquid: the reduce-only order it placed or the margin it added, with the answer it got." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsOrderOutcome": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "placed", "rejected", "uncertain", "cancelled", "applied", "not_executed" ], "description": "`placed` Hyperliquid accepted the order (see each placement), `rejected` it accepted none (or refused the margin change), `uncertain` the answer was lost and the host reconciles what is still unknown by client order id (a trailing stop with no answer only when one order matches its terms; a margin change from the account's own transaction list), `cancelled` the cancellation took effect, `applied` the margin change took effect, `not_executed` nothing was signed." }, "placements": { "maxItems": 4, "type": "array", "items": { "$ref": "#/components/schemas/PerpsPlacementOutcome" }, "description": "Each placement's own answer, in the order's order: entry, take-profit, stop-loss, then trailing stop." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why nothing was placed or the cancellation did not take effect, in Hyperliquid's or the host's words; null otherwise." } }, "required": [ "status", "placements", "reason" ], "description": "The result of one approved perps order, cancellation or margin change." }, "PerpsPlacementOutcome": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "entry", "take_profit", "stop_loss", "trailing_stop" ], "description": "Which part of the order: `entry`, `take_profit`, `stop_loss` or `trailing_stop`." }, "cloid": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-f]{32}$" }, { "type": "null" } ], "description": "The client order id it is reconciled by; null for a trailing stop, which Hyperliquid gives none and the host matches by its terms instead." }, "state": { "type": "string", "enum": [ "filled", "resting", "triggered_pending", "triggered", "cancelled", "rejected", "unknown" ], "description": "`filled` executed (possibly partly; see `filledSize`), `resting` waits on the book, `triggered_pending` is an exit waiting for its trigger, `triggered` is an exit whose trigger fired and became a market order (its fill is in the account's fills, not here), `rejected` never placed, `unknown` not yet known: never resubmit it." }, "oid": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Hyperliquid's order id once it named one; null for a trigger it answered without one, or an answer not yet known." }, "filledSize": { "description": "How much filled, in the coin, as Hyperliquid wrote it; null when nothing filled or it did not say.", "type": [ "string", "null" ] }, "averagePrice": { "description": "The average fill price, as Hyperliquid wrote it; null when it did not say.", "type": [ "string", "null" ] }, "error": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Hyperliquid's own refusal text for this placement; null otherwise." } }, "required": [ "role", "cloid", "state", "oid", "filledSize", "averagePrice", "error" ], "description": "What one placement of an order came to on Hyperliquid." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Delete an automation Stops an automation for good. Its history stays readable. Safe to repeat. `DELETE /v1/users/{userId}/automations/{automationId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request DELETE 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 204 The automation is deleted. ```json { "description": "The automation is deleted." } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `automation_changed` — the automation changed while this request was handled; read it again and retry ```json { "description": "The operation lost to the current state.\n\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.delete", "summary": "Delete an automation", "tags": [ "automations" ], "description": "Stops an automation for good. Its history stays readable. Safe to repeat.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "204": { "description": "The automation is deleted." }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Pause an automation 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. `POST /v1/users/{userId}/automations/{automationId}/pause` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID/pause' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The automation, updated. ```json { "description": "The automation, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `automation_changed` — the automation changed while this request was handled; read it again and retry ```json { "description": "The operation lost to the current state.\n\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 410 The resource still exists and stays readable, but can no longer take this request. - `automation_deleted` — the automation was deleted ```json { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `automation_deleted` — the automation was deleted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.pause", "summary": "Pause an automation", "tags": [ "automations" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "410": { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `automation_deleted` — the automation was deleted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "description": "The saved revision number. Use it to ignore older cached reads after chat edits. This server always returns it; earlier servers may omit it.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "description": "The automation's name." }, "prompt": { "type": "string", "description": "The instructions given to the model each time this automation fires." }, "rule": { "$ref": "#/components/schemas/AutomationRule" }, "missedRun": { "type": "string", "enum": [ "skip", "ask" ], "description": "What happens to a run that can't go through before its deadline: `skip` counts it and keeps the schedule, `ask` pauses the automation until its owner decides. A failure only the owner can fix pauses either way." }, "summary": { "type": "string", "description": "When the automation runs, in one readable sentence or two: its condition, then its schedule and run limit. Times are in UTC unless the schedule names its own time zone." }, "sourcePlans": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "result": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "ready", "description": "The binding is fully planned and ready to collect." }, "plan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "delivery": { "description": "Push delivery; absent means polling.", "type": "string", "const": "push" }, "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "How one binding will actually be collected: the operation, its guarantees and its configuration." } }, "required": [ "status", "plan" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "needs_connection", "description": "The binding is plannable but needs a connection the owner has not granted yet." }, "candidatePlan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "delivery": { "description": "Push delivery; absent means polling.", "type": "string", "const": "push" }, "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "The plan that would apply once the missing connection is granted." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "candidatePlan", "reasons" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unsupported", "description": "The binding cannot be planned at all, as asked." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "reasons" ] } ], "description": "Whether this binding is ready, needs a connection, or is unsupported, and why." } }, "required": [ "binding", "result" ] }, "description": "How each of the rule's bindings will actually be collected." }, "enabled": { "type": "boolean", "description": "Whether this automation is active: false while it is paused and once deleted." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation was last changed." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the automation was deleted; null while it exists." }, "hold": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the hold began." }, "reason": { "description": "Why an operator placed the hold, when they gave one.", "type": [ "string", "null" ] } }, "required": [ "at", "reason" ] }, { "type": "null" } ], "description": "An operator's hold: why future work is stopped, so the owner does not read it as their own doing." }, "waitingForOwner": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "add_funds", "edit_automation", "decide", "resume" ], "description": "What it needs: `add_funds`, `edit_automation`, `decide` whether to act now or keep it as it is, or `resume`: it can no longer read the data it watches until the owner resumes it, which reads that data afresh." }, "reason": { "type": "string", "description": "Why it stopped, one of the reasons a run gives: see `reason` on the automation run. A `resume` gives `unavailable`." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The automation run it paused over, or null for a `resume`, which no run caused." }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it paused." } }, "required": [ "action", "reason", "runId", "since" ] }, { "type": "null" } ], "description": "When fin paused this automation because only the owner can move it on: what it needs, and the run it stopped at when a run caused it. Null otherwise, including while the owner paused it themselves. Resuming clears it." }, "runCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many numbered runs it has had, the number its latest numbered run's `runNumber` reached. Exits and skipped checks are not counted." }, "skippedRunCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many of its runs were skipped: each failed, counted toward the run limit, and left the schedule as it was. A run it paused over is not one of them." }, "harvestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times it has taken a gain: harvest runs that settled at least in part. A run that failed, is uncertain or found nothing to trade isn't counted. Zero for an automation that doesn't harvest." }, "nextFireAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation's clock will next wake it, when it has a schedule and is enabled." }, "monitoring": { "$ref": "#/components/schemas/AutomationMonitoring" }, "activeRun": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRun" }, { "type": "null" } ], "description": "The automation run in progress or waiting to start, when there is one." }, "latestRun": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRun" }, { "type": "null" } ], "description": "The most recent automation run, finished or not, when there has been one." }, "contract": { "anyOf": [ { "type": "object", "properties": { "terms": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "oneOf": [ { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" } ], "description": "A standing Solana grant: an exact buy, or a sale of a fraction of the holding for USDC, made exactly as approved each time the automation fires." } ], "description": "The approved contract's exact terms." }, "approvedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the owner approved this contract." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this contract was withdrawn, when it has been." }, "executionsUsed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Executions that consumed the allowance. For a transfer contract, entry plans from the plan and leg ledger: an exit plan is exempt and never counted. For a perps automation, the firings whose exact order or funding was submitted. For a Solana grant, the firings whose trade or funding got past its first claim to sign." }, "spendUsed": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "description": "A capped input token of the approved contract." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "That token's decimals, copied from the approved cap." }, "spentRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the grant has spent of that token, raw. Claimed, signed, uncertain, settled and not-executed legs count, because a not-executed ending can follow a consumed deposit; only a refunded leg releases its part. The policy worker enforces the cap too and counts every debit it signed, refunded or not, so after a refund the room it grants can be smaller than this figure suggests." } }, "required": [ "tokenId", "decimals", "spentRaw" ] }, "description": "One entry for each capped input token, in the contract's order; empty when the contract has no total cap. The cap itself is terms.maxTotalInput, so the cap minus this is the most that is left: the policy worker, which signs, counts every debit it signed, refunded or not." }, "settledSpend": { "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "description": "A capped input token of the approved contract." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "That token's decimals, copied from the approved cap." }, "spentRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What has settled of that token, raw. Only settled legs count: nothing in flight, uncertain or not executed. A refunded leg counts nothing, a partly refunded one included, even though part of it may have been spent." } }, "required": [ "tokenId", "decimals", "spentRaw" ] }, "description": "What has actually settled of each capped input token, in the same shape as `spendUsed`: show this as what the automation spent, and `spendUsed` for what room is left. Unlike `spendUsed` it leaves out legs still in flight, uncertain, not executed or refunded. An edited grant's figure includes what it carried over, which can hold a not-executed debit from before the edit." } }, "required": [ "terms", "approvedAt", "revokedAt", "executionsUsed", "spendUsed", "settledSpend" ] }, { "type": "null" } ], "description": "The standing financial authority this automation's engine-fired runs execute under; null for an automation without one." } }, "required": [ "id", "name", "prompt", "rule", "missedRun", "summary", "sourcePlans", "enabled", "createdAt", "updatedAt", "deletedAt", "hold", "waitingForOwner", "runCount", "skippedRunCount", "harvestCount", "nextFireAt", "monitoring", "activeRun", "latestRun", "contract" ], "description": "One automation: its rule and a readable summary of it, its current sources, its monitoring health, and its runs." }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ] } }, "required": [ "intervalSeconds", "readers" ] }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ] }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "AutomationMonitoring": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable", "paused", "completed" ], "description": "The automation's overall monitoring status: `waiting` no evaluation yet, `healthy` sources and evaluation are current, `stale` an input is older than expected, `unavailable` a source could not be reached, `paused` firing is paused, `completed` its run policy is spent. A news exit (`rule.news`) reads `healthy` while Fin's news judge checks the news for it and `unavailable` while news checks are paused for its owner." }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When monitoring last checked this automation's sources." }, "sources": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "description": "The source's id within its provider." }, "check": { "description": "The most recent recipe check against this source, when evidence review is configured.", "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ] }, "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable" ], "description": "This source's health: `waiting` no observation yet, `healthy` fresh, `stale` older than expected, `unavailable` the provider could not be reached." }, "sourceTime": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the provider says the most recent observation was true." }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the engine received the most recent observation." }, "reason": { "description": "Why the source is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "binding", "sourceId", "status", "sourceTime", "receivedAt", "reason" ] }, "description": "Each bound source's own health." }, "lastEvaluation": { "anyOf": [ { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "true", "false", "unknown" ], "description": "Whether the condition holds: `true` it matches, `false` it does not, `unknown` usable input is missing. Firing policy, delivery, admission, budget and approvals separately decide whether matching can execute." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this evaluation ran." }, "reasons": { "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "nodePath": { "maxItems": 8, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "The path to the condition node this reason explains, as indices into the rule tree." }, "code": { "type": "string", "enum": [ "missing_source", "unavailable", "gap", "stale", "future", "missing_field", "invalid_value", "snapshot_skew" ], "description": "Why this node could not cleanly resolve: `missing_source` no binding was configured, `unavailable` the provider did not answer, `gap` a break in coverage was recorded, `stale` or `future` a timestamp was out of range, `missing_field` the observation lacked this field, `invalid_value` the value did not match its declared type, `snapshot_skew` the inputs disagreed on when they were true." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "nodePath", "code" ] }, "description": "Why the verdict is what it is, one entry per condition node that did not cleanly resolve." }, "inputs": { "maxItems": 5, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "snapshot", "description": "A point-in-time read of current state." }, "sourceTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the provider says this snapshot was true." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime" ] }, { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "received_event", "description": "An event the source pushed, or the engine collected as it happened." }, "sourceTime": { "type": "null", "description": "Not applicable to a received event; see `occurredAt` and `providerPublishedAt` instead." }, "providerPublishedAt": { "anyOf": [ { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When the provider says it published this event, when it reports one." }, "occurredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the event actually happened, when the provider reports that separately from when it was published." }, "finalizedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the provider considers this event no longer subject to correction, when it reports one." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime", "providerPublishedAt", "occurredAt", "finalizedAt" ] } ] }, "description": "Each input this evaluation read, without its raw data." } }, "required": [ "verdict", "evaluatedAt", "reasons", "inputs" ] }, { "type": "null" } ], "description": "The rule's most recent evaluation, when it has run at least once." }, "webhook": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether a webhook secret has been minted." }, "keyId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The current webhook secret's id, for rotation." }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the webhook last received a request." } }, "required": [ "configured", "keyId", "lastReceivedAt" ] }, { "type": "null" } ], "description": "This automation's owner webhook, when its rule has one; null for a news exit." }, "reason": { "description": "Why status is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "status", "lastCheckedAt", "sources", "lastEvaluation", "webhook", "reason" ], "description": "An automation's current health: its sources, its most recent evaluation, and its inbound webhook, if it has one." }, "AutomationRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run's id." }, "deliverySequence": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "This automation run's place in delivery order across all automations, as a string so it sorts and compares exactly at any size. A paging cursor, not a count of this automation's runs: `runNumber` is that." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The automation definition version this automation run was recorded under." }, "activationEpoch": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The activation epoch this automation run was recorded under." }, "name": { "type": "string", "description": "The automation's name when this automation run was recorded." }, "prompt": { "type": "string", "description": "The automation's prompt when this automation run was recorded." }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "decision", "external" ], "description": "What produced this automation run: `decision` the rule's own condition, `external` a source that decided on the engine's behalf." }, "identity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A stable string identifying this exact decision, used to deduplicate exact replays within one activation. Reuse with changed data conflicts." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this decision was made." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "The observations behind one decision, exactly as evaluated. Bounded to 256 KiB, 24 levels of nesting and 16384 entries." }, "sourceChecks": { "description": "Recipe checks recorded for each source this decision read, when evidence review is configured.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding this check was collected for." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The specific event or observation this check backs." }, "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this check ran." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "check": { "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ], "description": "A recorded run of a recipe's steps against the real source, kept as evidence." } }, "required": [ "binding", "sourceId", "eventId", "operationId", "operationVersion", "check" ], "description": "Frozen recipe evidence tied to the actual observation used by one decision." } } }, "required": [ "kind", "identity", "evaluatedAt", "data" ], "description": "Why this automation run happened: the decision, its evaluated data, and any recipe checks behind it." }, "selection": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "entry", "description": "This firing runs every entry action of the contract, in order." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exit", "description": "This firing runs exactly one exit action." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the approved exit action this firing selected." }, "exitKind": { "type": "string", "enum": [ "take_profit", "stop_loss", "harvest_every" ], "description": "Which guard fired: a take-profit, a stop-loss or a scheduled harvest." } }, "required": [ "kind", "actionIndex", "exitKind" ] } ], "description": "What this automation run's firing selected out of its contract: every entry action in order (`Scheduled buy`), or exactly one exit action (`Take-profit exit`/`Stop-loss exit`). A definition without a contract records `{ kind: \"entry\" }`." }, "state": { "type": "string", "enum": [ "pending", "deferred", "accepted", "retrying", "succeeded", "partial", "failed", "uncertain", "rejected", "canceled", "skipped", "coalesced" ], "description": "This automation run's state: `pending` waiting to start, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to an agent run, `retrying` waiting to try again before its deadline, `succeeded` it did what it was asked, `partial` only some of it went through, `failed` it moved nothing it was asked to, `uncertain` money may have moved and how it ended is not known yet, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before starting, `skipped` an earlier automation run was still active or it was missed, `coalesced` merged into a newer match." }, "reason": { "description": "Why the automation run is in this state, when there is one to give. A run that failed or went through only in part gives one of `unavailable`, `insufficient_funds`, `quote_rejected`, `not_authorized`, `not_executed` or `condition_passed`.", "type": [ "string", "null" ] }, "runNumber": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Which of its automation's runs this is, counting from 1, the number its run limit counts. Null for a run that is no scheduled or triggered firing of its own, such as an exit check selling a position. Show this, not `deliverySequence`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation run was recorded." }, "deliveryDeadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest this automation run could still start." }, "deadlineAt": { "description": "The latest this run may still try, once it has started: the earliest of its delivery deadline, the windows its owner signed and its next firing. Null or absent for a run that never started, or one from before this field. Use it, not `deliveryDeadline`, to say how long a run had.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "nextAttemptAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the next attempt to start this automation run is due." }, "lastAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation run was last tried, when it has been." }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many attempts to start this automation run there have been." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation this automation run works in, once it has one." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The agent run this automation run started, once it has one." }, "runStatus": { "anyOf": [ { "type": "string", "enum": [ "running", "paused", "completed", "failed", "aborted" ] }, { "type": "null" } ], "description": "That agent run's status, once it has one: `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "runError": { "description": "Why the agent run failed, when it did.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals this automation run's agent run is waiting on." }, "solana": { "description": "For a Solana trading automation, the admitted trade and its observed result. Absent or null before it acts and for other automations. Read this result independently of runStatus.", "anyOf": [ { "$ref": "#/components/schemas/AutomationRunSolana" }, { "type": "null" } ] }, "perps": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRunPerps" }, { "type": "null" } ], "description": "For a perps automation, the order this run placed or the margin it added, with Hyperliquid's answer. Null for any other automation, and until the run acts." } }, "required": [ "id", "deliverySequence", "automationId", "definitionVersion", "activationEpoch", "name", "prompt", "evidence", "selection", "state", "reason", "runNumber", "createdAt", "deliveryDeadline", "nextAttemptAt", "lastAttemptAt", "attempts", "conversationId", "runId", "runStatus", "runError", "pendingApprovals", "perps" ], "description": "One time an automation ran or was due to run: why, its delivery state, and the agent run it started, if any." }, "AutomationRunSolana": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "buy" }, "request": { "$ref": "#/components/schemas/SolanaBuyInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; an agent run completing does not prove that money moved." } }, "required": [ "id", "kind", "request", "outcome" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "sell" }, "request": { "$ref": "#/components/schemas/SolanaSellInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; a partial result may leave SOL in the Solana account." } }, "required": [ "id", "kind", "request", "outcome" ] } ], "description": "The Solana trade this automation run admitted, with its observed financial result." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "AutomationRunPerps": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "order", "description": "A reduce-only order on the automation's position." }, "order": { "description": "The exact order the run placed: the coin, side, size and worst price (`entry.price`) this firing allowed.", "$ref": "#/components/schemas/PerpsOrderInput" }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/PerpsOrderOutcome" }, { "type": "null" } ], "description": "Hyperliquid's answer, with each placement's fill. Null while the order is being sent or its answer is still being checked; the run never sends it twice." } }, "required": [ "kind", "order", "outcome" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "margin", "description": "Margin moved from the agent wallet to the perps account." }, "transfer": { "description": "The exact USDC amount the run moved, in six-decimal units, and its loss bound.", "$ref": "#/components/schemas/PerpsTransferInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "How the transfer ended. Null while it is still under way." } }, "required": [ "kind", "transfer", "outcome" ] } ], "description": "What one run of a perps automation did on Hyperliquid: the reduce-only order it placed or the margin it added, with the answer it got." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsOrderOutcome": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "placed", "rejected", "uncertain", "cancelled", "applied", "not_executed" ], "description": "`placed` Hyperliquid accepted the order (see each placement), `rejected` it accepted none (or refused the margin change), `uncertain` the answer was lost and the host reconciles what is still unknown by client order id (a trailing stop with no answer only when one order matches its terms; a margin change from the account's own transaction list), `cancelled` the cancellation took effect, `applied` the margin change took effect, `not_executed` nothing was signed." }, "placements": { "maxItems": 4, "type": "array", "items": { "$ref": "#/components/schemas/PerpsPlacementOutcome" }, "description": "Each placement's own answer, in the order's order: entry, take-profit, stop-loss, then trailing stop." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why nothing was placed or the cancellation did not take effect, in Hyperliquid's or the host's words; null otherwise." } }, "required": [ "status", "placements", "reason" ], "description": "The result of one approved perps order, cancellation or margin change." }, "PerpsPlacementOutcome": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "entry", "take_profit", "stop_loss", "trailing_stop" ], "description": "Which part of the order: `entry`, `take_profit`, `stop_loss` or `trailing_stop`." }, "cloid": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-f]{32}$" }, { "type": "null" } ], "description": "The client order id it is reconciled by; null for a trailing stop, which Hyperliquid gives none and the host matches by its terms instead." }, "state": { "type": "string", "enum": [ "filled", "resting", "triggered_pending", "triggered", "cancelled", "rejected", "unknown" ], "description": "`filled` executed (possibly partly; see `filledSize`), `resting` waits on the book, `triggered_pending` is an exit waiting for its trigger, `triggered` is an exit whose trigger fired and became a market order (its fill is in the account's fills, not here), `rejected` never placed, `unknown` not yet known: never resubmit it." }, "oid": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Hyperliquid's order id once it named one; null for a trigger it answered without one, or an answer not yet known." }, "filledSize": { "description": "How much filled, in the coin, as Hyperliquid wrote it; null when nothing filled or it did not say.", "type": [ "string", "null" ] }, "averagePrice": { "description": "The average fill price, as Hyperliquid wrote it; null when it did not say.", "type": [ "string", "null" ] }, "error": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Hyperliquid's own refusal text for this placement; null otherwise." } }, "required": [ "role", "cloid", "state", "oid", "filledSize", "averagePrice", "error" ], "description": "What one placement of an order came to on Hyperliquid." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Resume an automation 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. `POST /v1/users/{userId}/automations/{automationId}/resume` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string" }, "in": "query", "name": "countMissedRun", "required": false, "description": "Whether the owner let the run fin paused over go, so it counts toward the run limit. Leave it out to keep watching: the run goes back to the limit, and the automation carries on. It runs nothing it missed." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID/resume' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The automation, updated. ```json { "description": "The automation, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `automation_held` — an operator holds the automation; it fires again when released - `automation_invalid` — the automation's definition cannot run as written - `automation_changed` — the automation changed while this request was handled; read it again and retry ```json { "description": "The operation lost to the current state.\n\n- `automation_held` — an operator holds the automation; it fires again when released\n- `automation_invalid` — the automation's definition cannot run as written\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 410 The resource still exists and stays readable, but can no longer take this request. - `automation_deleted` — the automation was deleted ```json { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `automation_deleted` — the automation was deleted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.resume", "summary": "Resume an automation", "tags": [ "automations" ], "description": "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.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "countMissedRun", "required": false, "description": "Whether the owner let the run fin paused over go, so it counts toward the run limit. Leave it out to keep watching: the run goes back to the limit, and the automation carries on. It runs nothing it missed." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Automation" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_held` — an operator holds the automation; it fires again when released\n- `automation_invalid` — the automation's definition cannot run as written\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "410": { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `automation_deleted` — the automation was deleted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "Automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "description": "The saved revision number. Use it to ignore older cached reads after chat edits. This server always returns it; earlier servers may omit it.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "description": "The automation's name." }, "prompt": { "type": "string", "description": "The instructions given to the model each time this automation fires." }, "rule": { "$ref": "#/components/schemas/AutomationRule" }, "missedRun": { "type": "string", "enum": [ "skip", "ask" ], "description": "What happens to a run that can't go through before its deadline: `skip` counts it and keeps the schedule, `ask` pauses the automation until its owner decides. A failure only the owner can fix pauses either way." }, "summary": { "type": "string", "description": "When the automation runs, in one readable sentence or two: its condition, then its schedule and run limit. Times are in UTC unless the schedule names its own time zone." }, "sourcePlans": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "result": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "ready", "description": "The binding is fully planned and ready to collect." }, "plan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "delivery": { "description": "Push delivery; absent means polling.", "type": "string", "const": "push" }, "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "How one binding will actually be collected: the operation, its guarantees and its configuration." } }, "required": [ "status", "plan" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "needs_connection", "description": "The binding is plannable but needs a connection the owner has not granted yet." }, "candidatePlan": { "type": "object", "properties": { "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this plan uses." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "descriptorFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash of the source descriptor this plan was built from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." }, "guarantees": { "type": "object", "properties": { "delivery": { "description": "Push delivery; absent means polling.", "type": "string", "const": "push" }, "minCadenceSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "The shortest interval between requests the provider permits, in seconds." }, "expectedLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483 }, { "type": "null" } ], "description": "How stale the provider's own value may be when it answers, in seconds; null when the provider establishes no bound. A reader with a delivery deadline cannot use a source that promises nothing here." }, "maxAgeSeconds": { "type": "integer", "minimum": 0, "maximum": 2147483, "description": "Maximum snapshot observation age accepted at collection. This acquisition guarantee does not shorten a reader's separately declared evaluation-age window." }, "requestsPerMinute": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The provider's own rate limit for this source, when it publishes one." }, "observationReuseSeconds": { "description": "How long one provider observation may serve every reader watching the same subject under the same connection, in seconds. Absent or 0 means each reader causes its own request. A reused observation keeps the provider's own `sourceTime`, so declared freshness still governs; what reuse changes is how often the provider is asked, not how old an accepted observation may be. Keep it at or below the cadence readers are expected to poll at.", "type": "integer", "minimum": 0, "maximum": 2147483 }, "batchLimit": { "description": "How many distinct subjects the provider can serve in one request. Absent or 1 means no batching. Only providers implementing `readBatch` may declare more: the framework cannot infer that an API accepts several subjects.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "minCadenceSeconds", "expectedLatencySeconds", "maxAgeSeconds", "requestsPerMinute" ], "description": "What an operation promises about the snapshots it serves: cadence, freshness and how many subjects it can batch. Describes sampled state; nothing here promises that a change between two polls was seen." }, "scopeKind": { "type": "string", "enum": [ "public", "user" ], "description": "Who this binding is scoped to: `public` data anyone can read, `user` data read under the owner's own connection." }, "explanation": { "type": "string", "maxLength": 2048, "description": "Why this plan was chosen, in the reviewer's own words." }, "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "degraded": { "type": "boolean", "description": "Whether this plan settled for weaker guarantees than the rule asked for." } }, "required": [ "operationId", "operationVersion", "descriptorFingerprint", "config", "requirement", "guarantees", "scopeKind", "explanation", "degraded" ], "description": "The plan that would apply once the missing connection is granted." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "candidatePlan", "reasons" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unsupported", "description": "The binding cannot be planned at all, as asked." }, "reasons": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A machine-readable reason code." }, "path": { "description": "The field this reason is about, when it is about one.", "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 2048, "description": "The reason, in the reviewer's own words." } }, "required": [ "code", "message" ] }, "description": "Why this binding could not be planned as asked." } }, "required": [ "status", "reasons" ] } ], "description": "Whether this binding is ready, needs a connection, or is unsupported, and why." } }, "required": [ "binding", "result" ] }, "description": "How each of the rule's bindings will actually be collected." }, "enabled": { "type": "boolean", "description": "Whether this automation is active: false while it is paused and once deleted." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation was created." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation was last changed." }, "deletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the automation was deleted; null while it exists." }, "hold": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the hold began." }, "reason": { "description": "Why an operator placed the hold, when they gave one.", "type": [ "string", "null" ] } }, "required": [ "at", "reason" ] }, { "type": "null" } ], "description": "An operator's hold: why future work is stopped, so the owner does not read it as their own doing." }, "waitingForOwner": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "add_funds", "edit_automation", "decide", "resume" ], "description": "What it needs: `add_funds`, `edit_automation`, `decide` whether to act now or keep it as it is, or `resume`: it can no longer read the data it watches until the owner resumes it, which reads that data afresh." }, "reason": { "type": "string", "description": "Why it stopped, one of the reasons a run gives: see `reason` on the automation run. A `resume` gives `unavailable`." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The automation run it paused over, or null for a `resume`, which no run caused." }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it paused." } }, "required": [ "action", "reason", "runId", "since" ] }, { "type": "null" } ], "description": "When fin paused this automation because only the owner can move it on: what it needs, and the run it stopped at when a run caused it. Null otherwise, including while the owner paused it themselves. Resuming clears it." }, "runCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many numbered runs it has had, the number its latest numbered run's `runNumber` reached. Exits and skipped checks are not counted." }, "skippedRunCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many of its runs were skipped: each failed, counted toward the run limit, and left the schedule as it was. A run it paused over is not one of them." }, "harvestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many times it has taken a gain: harvest runs that settled at least in part. A run that failed, is uncertain or found nothing to trade isn't counted. Zero for an automation that doesn't harvest." }, "nextFireAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation's clock will next wake it, when it has a schedule and is enabled." }, "monitoring": { "$ref": "#/components/schemas/AutomationMonitoring" }, "activeRun": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRun" }, { "type": "null" } ], "description": "The automation run in progress or waiting to start, when there is one." }, "latestRun": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRun" }, { "type": "null" } ], "description": "The most recent automation run, finished or not, when there has been one." }, "contract": { "anyOf": [ { "type": "object", "properties": { "terms": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "near_intents_transfer", "description": "Which contract template this is." }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "swap", "description": "Exchange one asset for another; custody never leaves the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "take_profit", "description": "Sell when the asset is this far ABOVE the automation's average cost." }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "stop_loss", "description": "Sell when the asset is this far BELOW the automation's average cost." }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "harvest_every", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled." }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_to_owner", "description": "Return an asset to the account that owns the agent wallet." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "withdraw_transfer", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "send", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer." }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_tokens", "description": "Spend an exact amount of the input token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_input_value_usd", "description": "Spend a USD-denominated value of the input token." }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exact_output_tokens", "description": "Receive an exact amount of the output token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "all_of_input", "description": "Spend everything the agent wallet holds of the input asset." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_input", "description": "Spend a fraction of the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction_of_position", "description": "Sell a fraction of this automation's own position in the input asset." }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "gain_of_position", "description": "Sell only the gain on this automation's own position in the input asset." } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "const": true, "description": "Any token the agent wallet holds; the executor picks one at execution." } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "dependency_graph" }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "oneOf": [ { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" } ], "description": "A standing Solana grant: an exact buy, or a sale of a fraction of the holding for USDC, made exactly as approved each time the automation fires." } ], "description": "The approved contract's exact terms." }, "approvedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the owner approved this contract." }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this contract was withdrawn, when it has been." }, "executionsUsed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Executions that consumed the allowance. For a transfer contract, entry plans from the plan and leg ledger: an exit plan is exempt and never counted. For a perps automation, the firings whose exact order or funding was submitted. For a Solana grant, the firings whose trade or funding got past its first claim to sign." }, "spendUsed": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "description": "A capped input token of the approved contract." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "That token's decimals, copied from the approved cap." }, "spentRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What the grant has spent of that token, raw. Claimed, signed, uncertain, settled and not-executed legs count, because a not-executed ending can follow a consumed deposit; only a refunded leg releases its part. The policy worker enforces the cap too and counts every debit it signed, refunded or not, so after a refund the room it grants can be smaller than this figure suggests." } }, "required": [ "tokenId", "decimals", "spentRaw" ] }, "description": "One entry for each capped input token, in the contract's order; empty when the contract has no total cap. The cap itself is terms.maxTotalInput, so the cap minus this is the most that is left: the policy worker, which signs, counts every debit it signed, refunded or not." }, "settledSpend": { "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "minLength": 1, "description": "A capped input token of the approved contract." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "That token's decimals, copied from the approved cap." }, "spentRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "What has settled of that token, raw. Only settled legs count: nothing in flight, uncertain or not executed. A refunded leg counts nothing, a partly refunded one included, even though part of it may have been spent." } }, "required": [ "tokenId", "decimals", "spentRaw" ] }, "description": "What has actually settled of each capped input token, in the same shape as `spendUsed`: show this as what the automation spent, and `spendUsed` for what room is left. Unlike `spendUsed` it leaves out legs still in flight, uncertain, not executed or refunded. An edited grant's figure includes what it carried over, which can hold a not-executed debit from before the edit." } }, "required": [ "terms", "approvedAt", "revokedAt", "executionsUsed", "spendUsed", "settledSpend" ] }, { "type": "null" } ], "description": "The standing financial authority this automation's engine-fired runs execute under; null for an automation without one." } }, "required": [ "id", "name", "prompt", "rule", "missedRun", "summary", "sourcePlans", "enabled", "createdAt", "updatedAt", "deletedAt", "hold", "waitingForOwner", "runCount", "skippedRunCount", "harvestCount", "nextFireAt", "monitoring", "activeRun", "latestRun", "contract" ], "description": "One automation: its rule and a readable summary of it, its current sources, its monitoring health, and its runs." }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ] } }, "required": [ "intervalSeconds", "readers" ] }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ] }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "AutomationMonitoring": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable", "paused", "completed" ], "description": "The automation's overall monitoring status: `waiting` no evaluation yet, `healthy` sources and evaluation are current, `stale` an input is older than expected, `unavailable` a source could not be reached, `paused` firing is paused, `completed` its run policy is spent. A news exit (`rule.news`) reads `healthy` while Fin's news judge checks the news for it and `unavailable` while news checks are paused for its owner." }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When monitoring last checked this automation's sources." }, "sources": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "description": "The source's id within its provider." }, "check": { "description": "The most recent recipe check against this source, when evidence review is configured.", "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ] }, "status": { "type": "string", "enum": [ "waiting", "healthy", "stale", "unavailable" ], "description": "This source's health: `waiting` no observation yet, `healthy` fresh, `stale` older than expected, `unavailable` the provider could not be reached." }, "sourceTime": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the provider says the most recent observation was true." }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the engine received the most recent observation." }, "reason": { "description": "Why the source is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "binding", "sourceId", "status", "sourceTime", "receivedAt", "reason" ] }, "description": "Each bound source's own health." }, "lastEvaluation": { "anyOf": [ { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "true", "false", "unknown" ], "description": "Whether the condition holds: `true` it matches, `false` it does not, `unknown` usable input is missing. Firing policy, delivery, admission, budget and approvals separately decide whether matching can execute." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this evaluation ran." }, "reasons": { "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "nodePath": { "maxItems": 8, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "The path to the condition node this reason explains, as indices into the rule tree." }, "code": { "type": "string", "enum": [ "missing_source", "unavailable", "gap", "stale", "future", "missing_field", "invalid_value", "snapshot_skew" ], "description": "Why this node could not cleanly resolve: `missing_source` no binding was configured, `unavailable` the provider did not answer, `gap` a break in coverage was recorded, `stale` or `future` a timestamp was out of range, `missing_field` the observation lacked this field, `invalid_value` the value did not match its declared type, `snapshot_skew` the inputs disagreed on when they were true." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "nodePath", "code" ] }, "description": "Why the verdict is what it is, one entry per condition node that did not cleanly resolve." }, "inputs": { "maxItems": 5, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "snapshot", "description": "A point-in-time read of current state." }, "sourceTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the provider says this snapshot was true." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime" ] }, { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The observation or event's id." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the engine received this observation." }, "maxAgeSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How old this observation was allowed to be at evaluation, in seconds." }, "status": { "type": "string", "enum": [ "ready", "unavailable", "gap" ], "description": "Whether this input was ready to evaluate, the provider was unavailable, or a gap was recorded instead." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why the input is not ready, when it is not." }, "kind": { "type": "string", "const": "received_event", "description": "An event the source pushed, or the engine collected as it happened." }, "sourceTime": { "type": "null", "description": "Not applicable to a received event; see `occurredAt` and `providerPublishedAt` instead." }, "providerPublishedAt": { "anyOf": [ { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ], "description": "When the provider says it published this event, when it reports one." }, "occurredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the event actually happened, when the provider reports that separately from when it was published." }, "finalizedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the provider considers this event no longer subject to correction, when it reports one." } }, "required": [ "binding", "sourceId", "eventId", "receivedAt", "maxAgeSeconds", "status", "reason", "kind", "sourceTime", "providerPublishedAt", "occurredAt", "finalizedAt" ] } ] }, "description": "Each input this evaluation read, without its raw data." } }, "required": [ "verdict", "evaluatedAt", "reasons", "inputs" ] }, { "type": "null" } ], "description": "The rule's most recent evaluation, when it has run at least once." }, "webhook": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "description": "Whether a webhook secret has been minted." }, "keyId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The current webhook secret's id, for rotation." }, "lastReceivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the webhook last received a request." } }, "required": [ "configured", "keyId", "lastReceivedAt" ] }, { "type": "null" } ], "description": "This automation's owner webhook, when its rule has one; null for a news exit." }, "reason": { "description": "Why status is not healthy, when it is not.", "type": [ "string", "null" ] } }, "required": [ "status", "lastCheckedAt", "sources", "lastEvaluation", "webhook", "reason" ], "description": "An automation's current health: its sources, its most recent evaluation, and its inbound webhook, if it has one." }, "AutomationRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run's id." }, "deliverySequence": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "This automation run's place in delivery order across all automations, as a string so it sorts and compares exactly at any size. A paging cursor, not a count of this automation's runs: `runNumber` is that." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The automation definition version this automation run was recorded under." }, "activationEpoch": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The activation epoch this automation run was recorded under." }, "name": { "type": "string", "description": "The automation's name when this automation run was recorded." }, "prompt": { "type": "string", "description": "The automation's prompt when this automation run was recorded." }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "decision", "external" ], "description": "What produced this automation run: `decision` the rule's own condition, `external` a source that decided on the engine's behalf." }, "identity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A stable string identifying this exact decision, used to deduplicate exact replays within one activation. Reuse with changed data conflicts." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this decision was made." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "The observations behind one decision, exactly as evaluated. Bounded to 256 KiB, 24 levels of nesting and 16384 entries." }, "sourceChecks": { "description": "Recipe checks recorded for each source this decision read, when evidence review is configured.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding this check was collected for." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The specific event or observation this check backs." }, "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this check ran." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "check": { "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ], "description": "A recorded run of a recipe's steps against the real source, kept as evidence." } }, "required": [ "binding", "sourceId", "eventId", "operationId", "operationVersion", "check" ], "description": "Frozen recipe evidence tied to the actual observation used by one decision." } } }, "required": [ "kind", "identity", "evaluatedAt", "data" ], "description": "Why this automation run happened: the decision, its evaluated data, and any recipe checks behind it." }, "selection": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "entry", "description": "This firing runs every entry action of the contract, in order." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exit", "description": "This firing runs exactly one exit action." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the approved exit action this firing selected." }, "exitKind": { "type": "string", "enum": [ "take_profit", "stop_loss", "harvest_every" ], "description": "Which guard fired: a take-profit, a stop-loss or a scheduled harvest." } }, "required": [ "kind", "actionIndex", "exitKind" ] } ], "description": "What this automation run's firing selected out of its contract: every entry action in order (`Scheduled buy`), or exactly one exit action (`Take-profit exit`/`Stop-loss exit`). A definition without a contract records `{ kind: \"entry\" }`." }, "state": { "type": "string", "enum": [ "pending", "deferred", "accepted", "retrying", "succeeded", "partial", "failed", "uncertain", "rejected", "canceled", "skipped", "coalesced" ], "description": "This automation run's state: `pending` waiting to start, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to an agent run, `retrying` waiting to try again before its deadline, `succeeded` it did what it was asked, `partial` only some of it went through, `failed` it moved nothing it was asked to, `uncertain` money may have moved and how it ended is not known yet, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before starting, `skipped` an earlier automation run was still active or it was missed, `coalesced` merged into a newer match." }, "reason": { "description": "Why the automation run is in this state, when there is one to give. A run that failed or went through only in part gives one of `unavailable`, `insufficient_funds`, `quote_rejected`, `not_authorized`, `not_executed` or `condition_passed`.", "type": [ "string", "null" ] }, "runNumber": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Which of its automation's runs this is, counting from 1, the number its run limit counts. Null for a run that is no scheduled or triggered firing of its own, such as an exit check selling a position. Show this, not `deliverySequence`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation run was recorded." }, "deliveryDeadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest this automation run could still start." }, "deadlineAt": { "description": "The latest this run may still try, once it has started: the earliest of its delivery deadline, the windows its owner signed and its next firing. Null or absent for a run that never started, or one from before this field. Use it, not `deliveryDeadline`, to say how long a run had.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "nextAttemptAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the next attempt to start this automation run is due." }, "lastAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation run was last tried, when it has been." }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many attempts to start this automation run there have been." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation this automation run works in, once it has one." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The agent run this automation run started, once it has one." }, "runStatus": { "anyOf": [ { "type": "string", "enum": [ "running", "paused", "completed", "failed", "aborted" ] }, { "type": "null" } ], "description": "That agent run's status, once it has one: `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "runError": { "description": "Why the agent run failed, when it did.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals this automation run's agent run is waiting on." }, "solana": { "description": "For a Solana trading automation, the admitted trade and its observed result. Absent or null before it acts and for other automations. Read this result independently of runStatus.", "anyOf": [ { "$ref": "#/components/schemas/AutomationRunSolana" }, { "type": "null" } ] }, "perps": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRunPerps" }, { "type": "null" } ], "description": "For a perps automation, the order this run placed or the margin it added, with Hyperliquid's answer. Null for any other automation, and until the run acts." } }, "required": [ "id", "deliverySequence", "automationId", "definitionVersion", "activationEpoch", "name", "prompt", "evidence", "selection", "state", "reason", "runNumber", "createdAt", "deliveryDeadline", "nextAttemptAt", "lastAttemptAt", "attempts", "conversationId", "runId", "runStatus", "runError", "pendingApprovals", "perps" ], "description": "One time an automation ran or was due to run: why, its delivery state, and the agent run it started, if any." }, "AutomationRunSolana": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "buy" }, "request": { "$ref": "#/components/schemas/SolanaBuyInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; an agent run completing does not prove that money moved." } }, "required": [ "id", "kind", "request", "outcome" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "sell" }, "request": { "$ref": "#/components/schemas/SolanaSellInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; a partial result may leave SOL in the Solana account." } }, "required": [ "id", "kind", "request", "outcome" ] } ], "description": "The Solana trade this automation run admitted, with its observed financial result." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "AutomationRunPerps": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "order", "description": "A reduce-only order on the automation's position." }, "order": { "description": "The exact order the run placed: the coin, side, size and worst price (`entry.price`) this firing allowed.", "$ref": "#/components/schemas/PerpsOrderInput" }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/PerpsOrderOutcome" }, { "type": "null" } ], "description": "Hyperliquid's answer, with each placement's fill. Null while the order is being sent or its answer is still being checked; the run never sends it twice." } }, "required": [ "kind", "order", "outcome" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "margin", "description": "Margin moved from the agent wallet to the perps account." }, "transfer": { "description": "The exact USDC amount the run moved, in six-decimal units, and its loss bound.", "$ref": "#/components/schemas/PerpsTransferInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "How the transfer ended. Null while it is still under way." } }, "required": [ "kind", "transfer", "outcome" ] } ], "description": "What one run of a perps automation did on Hyperliquid: the reduce-only order it placed or the margin it added, with the answer it got." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsOrderOutcome": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "placed", "rejected", "uncertain", "cancelled", "applied", "not_executed" ], "description": "`placed` Hyperliquid accepted the order (see each placement), `rejected` it accepted none (or refused the margin change), `uncertain` the answer was lost and the host reconciles what is still unknown by client order id (a trailing stop with no answer only when one order matches its terms; a margin change from the account's own transaction list), `cancelled` the cancellation took effect, `applied` the margin change took effect, `not_executed` nothing was signed." }, "placements": { "maxItems": 4, "type": "array", "items": { "$ref": "#/components/schemas/PerpsPlacementOutcome" }, "description": "Each placement's own answer, in the order's order: entry, take-profit, stop-loss, then trailing stop." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why nothing was placed or the cancellation did not take effect, in Hyperliquid's or the host's words; null otherwise." } }, "required": [ "status", "placements", "reason" ], "description": "The result of one approved perps order, cancellation or margin change." }, "PerpsPlacementOutcome": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "entry", "take_profit", "stop_loss", "trailing_stop" ], "description": "Which part of the order: `entry`, `take_profit`, `stop_loss` or `trailing_stop`." }, "cloid": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-f]{32}$" }, { "type": "null" } ], "description": "The client order id it is reconciled by; null for a trailing stop, which Hyperliquid gives none and the host matches by its terms instead." }, "state": { "type": "string", "enum": [ "filled", "resting", "triggered_pending", "triggered", "cancelled", "rejected", "unknown" ], "description": "`filled` executed (possibly partly; see `filledSize`), `resting` waits on the book, `triggered_pending` is an exit waiting for its trigger, `triggered` is an exit whose trigger fired and became a market order (its fill is in the account's fills, not here), `rejected` never placed, `unknown` not yet known: never resubmit it." }, "oid": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Hyperliquid's order id once it named one; null for a trigger it answered without one, or an answer not yet known." }, "filledSize": { "description": "How much filled, in the coin, as Hyperliquid wrote it; null when nothing filled or it did not say.", "type": [ "string", "null" ] }, "averagePrice": { "description": "The average fill price, as Hyperliquid wrote it; null when it did not say.", "type": [ "string", "null" ] }, "error": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Hyperliquid's own refusal text for this placement; null otherwise." } }, "required": [ "role", "cloid", "state", "oid", "filledSize", "averagePrice", "error" ], "description": "What one placement of an order came to on Hyperliquid." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List an automation's runs Lists each time the automation ran or was due to run, newest first, with the outcome and the agent run it started. `GET /v1/users/{userId}/automations/{automationId}/runs` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID/runs' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The automation's runs. ```json { "description": "The automation's runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRun" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.listRuns", "summary": "List an automation's runs", "tags": [ "automations" ], "description": "Lists each time the automation ran or was due to run, newest first, with the outcome and the agent run it started.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation's runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRun" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "AutomationRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run's id." }, "deliverySequence": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "This automation run's place in delivery order across all automations, as a string so it sorts and compares exactly at any size. A paging cursor, not a count of this automation's runs: `runNumber` is that." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The automation definition version this automation run was recorded under." }, "activationEpoch": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The activation epoch this automation run was recorded under." }, "name": { "type": "string", "description": "The automation's name when this automation run was recorded." }, "prompt": { "type": "string", "description": "The automation's prompt when this automation run was recorded." }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "decision", "external" ], "description": "What produced this automation run: `decision` the rule's own condition, `external` a source that decided on the engine's behalf." }, "identity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A stable string identifying this exact decision, used to deduplicate exact replays within one activation. Reuse with changed data conflicts." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this decision was made." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "The observations behind one decision, exactly as evaluated. Bounded to 256 KiB, 24 levels of nesting and 16384 entries." }, "sourceChecks": { "description": "Recipe checks recorded for each source this decision read, when evidence review is configured.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding this check was collected for." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The specific event or observation this check backs." }, "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this check ran." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "check": { "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ], "description": "A recorded run of a recipe's steps against the real source, kept as evidence." } }, "required": [ "binding", "sourceId", "eventId", "operationId", "operationVersion", "check" ], "description": "Frozen recipe evidence tied to the actual observation used by one decision." } } }, "required": [ "kind", "identity", "evaluatedAt", "data" ], "description": "Why this automation run happened: the decision, its evaluated data, and any recipe checks behind it." }, "selection": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "entry", "description": "This firing runs every entry action of the contract, in order." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exit", "description": "This firing runs exactly one exit action." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the approved exit action this firing selected." }, "exitKind": { "type": "string", "enum": [ "take_profit", "stop_loss", "harvest_every" ], "description": "Which guard fired: a take-profit, a stop-loss or a scheduled harvest." } }, "required": [ "kind", "actionIndex", "exitKind" ] } ], "description": "What this automation run's firing selected out of its contract: every entry action in order (`Scheduled buy`), or exactly one exit action (`Take-profit exit`/`Stop-loss exit`). A definition without a contract records `{ kind: \"entry\" }`." }, "state": { "type": "string", "enum": [ "pending", "deferred", "accepted", "retrying", "succeeded", "partial", "failed", "uncertain", "rejected", "canceled", "skipped", "coalesced" ], "description": "This automation run's state: `pending` waiting to start, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to an agent run, `retrying` waiting to try again before its deadline, `succeeded` it did what it was asked, `partial` only some of it went through, `failed` it moved nothing it was asked to, `uncertain` money may have moved and how it ended is not known yet, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before starting, `skipped` an earlier automation run was still active or it was missed, `coalesced` merged into a newer match." }, "reason": { "description": "Why the automation run is in this state, when there is one to give. A run that failed or went through only in part gives one of `unavailable`, `insufficient_funds`, `quote_rejected`, `not_authorized`, `not_executed` or `condition_passed`.", "type": [ "string", "null" ] }, "runNumber": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Which of its automation's runs this is, counting from 1, the number its run limit counts. Null for a run that is no scheduled or triggered firing of its own, such as an exit check selling a position. Show this, not `deliverySequence`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation run was recorded." }, "deliveryDeadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest this automation run could still start." }, "deadlineAt": { "description": "The latest this run may still try, once it has started: the earliest of its delivery deadline, the windows its owner signed and its next firing. Null or absent for a run that never started, or one from before this field. Use it, not `deliveryDeadline`, to say how long a run had.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "nextAttemptAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the next attempt to start this automation run is due." }, "lastAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation run was last tried, when it has been." }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many attempts to start this automation run there have been." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation this automation run works in, once it has one." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The agent run this automation run started, once it has one." }, "runStatus": { "anyOf": [ { "type": "string", "enum": [ "running", "paused", "completed", "failed", "aborted" ] }, { "type": "null" } ], "description": "That agent run's status, once it has one: `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "runError": { "description": "Why the agent run failed, when it did.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals this automation run's agent run is waiting on." }, "solana": { "description": "For a Solana trading automation, the admitted trade and its observed result. Absent or null before it acts and for other automations. Read this result independently of runStatus.", "anyOf": [ { "$ref": "#/components/schemas/AutomationRunSolana" }, { "type": "null" } ] }, "perps": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRunPerps" }, { "type": "null" } ], "description": "For a perps automation, the order this run placed or the margin it added, with Hyperliquid's answer. Null for any other automation, and until the run acts." } }, "required": [ "id", "deliverySequence", "automationId", "definitionVersion", "activationEpoch", "name", "prompt", "evidence", "selection", "state", "reason", "runNumber", "createdAt", "deliveryDeadline", "nextAttemptAt", "lastAttemptAt", "attempts", "conversationId", "runId", "runStatus", "runError", "pendingApprovals", "perps" ], "description": "One time an automation ran or was due to run: why, its delivery state, and the agent run it started, if any." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "AutomationRunSolana": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "buy" }, "request": { "$ref": "#/components/schemas/SolanaBuyInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; an agent run completing does not prove that money moved." } }, "required": [ "id", "kind", "request", "outcome" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "sell" }, "request": { "$ref": "#/components/schemas/SolanaSellInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; a partial result may leave SOL in the Solana account." } }, "required": [ "id", "kind", "request", "outcome" ] } ], "description": "The Solana trade this automation run admitted, with its observed financial result." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "AutomationRunPerps": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "order", "description": "A reduce-only order on the automation's position." }, "order": { "description": "The exact order the run placed: the coin, side, size and worst price (`entry.price`) this firing allowed.", "$ref": "#/components/schemas/PerpsOrderInput" }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/PerpsOrderOutcome" }, { "type": "null" } ], "description": "Hyperliquid's answer, with each placement's fill. Null while the order is being sent or its answer is still being checked; the run never sends it twice." } }, "required": [ "kind", "order", "outcome" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "margin", "description": "Margin moved from the agent wallet to the perps account." }, "transfer": { "description": "The exact USDC amount the run moved, in six-decimal units, and its loss bound.", "$ref": "#/components/schemas/PerpsTransferInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "How the transfer ended. Null while it is still under way." } }, "required": [ "kind", "transfer", "outcome" ] } ], "description": "What one run of a perps automation did on Hyperliquid: the reduce-only order it placed or the margin it added, with the answer it got." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsOrderOutcome": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "placed", "rejected", "uncertain", "cancelled", "applied", "not_executed" ], "description": "`placed` Hyperliquid accepted the order (see each placement), `rejected` it accepted none (or refused the margin change), `uncertain` the answer was lost and the host reconciles what is still unknown by client order id (a trailing stop with no answer only when one order matches its terms; a margin change from the account's own transaction list), `cancelled` the cancellation took effect, `applied` the margin change took effect, `not_executed` nothing was signed." }, "placements": { "maxItems": 4, "type": "array", "items": { "$ref": "#/components/schemas/PerpsPlacementOutcome" }, "description": "Each placement's own answer, in the order's order: entry, take-profit, stop-loss, then trailing stop." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why nothing was placed or the cancellation did not take effect, in Hyperliquid's or the host's words; null otherwise." } }, "required": [ "status", "placements", "reason" ], "description": "The result of one approved perps order, cancellation or margin change." }, "PerpsPlacementOutcome": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "entry", "take_profit", "stop_loss", "trailing_stop" ], "description": "Which part of the order: `entry`, `take_profit`, `stop_loss` or `trailing_stop`." }, "cloid": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-f]{32}$" }, { "type": "null" } ], "description": "The client order id it is reconciled by; null for a trailing stop, which Hyperliquid gives none and the host matches by its terms instead." }, "state": { "type": "string", "enum": [ "filled", "resting", "triggered_pending", "triggered", "cancelled", "rejected", "unknown" ], "description": "`filled` executed (possibly partly; see `filledSize`), `resting` waits on the book, `triggered_pending` is an exit waiting for its trigger, `triggered` is an exit whose trigger fired and became a market order (its fill is in the account's fills, not here), `rejected` never placed, `unknown` not yet known: never resubmit it." }, "oid": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Hyperliquid's order id once it named one; null for a trigger it answered without one, or an answer not yet known." }, "filledSize": { "description": "How much filled, in the coin, as Hyperliquid wrote it; null when nothing filled or it did not say.", "type": [ "string", "null" ] }, "averagePrice": { "description": "The average fill price, as Hyperliquid wrote it; null when it did not say.", "type": [ "string", "null" ] }, "error": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Hyperliquid's own refusal text for this placement; null otherwise." } }, "required": [ "role", "cloid", "state", "oid", "filledSize", "averagePrice", "error" ], "description": "What one placement of an order came to on Hyperliquid." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Get an automation run Returns one time the automation ran: when and why, whether it started or was skipped, and the agent run and approvals involved. `GET /v1/users/{userId}/automations/{automationId}/runs/{automationRunId}` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationRunId", "required": true, "description": "The automation run's `id`, from List an automation's runs." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID/runs/YOUR_AUTOMATION_RUN_ID' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The automation run. ```json { "description": "The automation run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRun" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.getRun", "summary": "Get an automation run", "tags": [ "automations" ], "description": "Returns one time the automation ran: when and why, whether it started or was skipped, and the agent run and approvals involved.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationRunId", "required": true, "description": "The automation run's `id`, from List an automation's runs." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRun" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "AutomationRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation run's id." }, "deliverySequence": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "This automation run's place in delivery order across all automations, as a string so it sorts and compares exactly at any size. A paging cursor, not a count of this automation's runs: `runNumber` is that." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The automation definition version this automation run was recorded under." }, "activationEpoch": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The activation epoch this automation run was recorded under." }, "name": { "type": "string", "description": "The automation's name when this automation run was recorded." }, "prompt": { "type": "string", "description": "The automation's prompt when this automation run was recorded." }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "decision", "external" ], "description": "What produced this automation run: `decision` the rule's own condition, `external` a source that decided on the engine's behalf." }, "identity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A stable string identifying this exact decision, used to deduplicate exact replays within one activation. Reuse with changed data conflicts." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this decision was made." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "The observations behind one decision, exactly as evaluated. Bounded to 256 KiB, 24 levels of nesting and 16384 entries." }, "sourceChecks": { "description": "Recipe checks recorded for each source this decision read, when evidence review is configured.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding this check was collected for." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The specific event or observation this check backs." }, "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this check ran." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "check": { "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ], "description": "A recorded run of a recipe's steps against the real source, kept as evidence." } }, "required": [ "binding", "sourceId", "eventId", "operationId", "operationVersion", "check" ], "description": "Frozen recipe evidence tied to the actual observation used by one decision." } } }, "required": [ "kind", "identity", "evaluatedAt", "data" ], "description": "Why this automation run happened: the decision, its evaluated data, and any recipe checks behind it." }, "selection": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "entry", "description": "This firing runs every entry action of the contract, in order." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "exit", "description": "This firing runs exactly one exit action." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The zero-based index of the approved exit action this firing selected." }, "exitKind": { "type": "string", "enum": [ "take_profit", "stop_loss", "harvest_every" ], "description": "Which guard fired: a take-profit, a stop-loss or a scheduled harvest." } }, "required": [ "kind", "actionIndex", "exitKind" ] } ], "description": "What this automation run's firing selected out of its contract: every entry action in order (`Scheduled buy`), or exactly one exit action (`Take-profit exit`/`Stop-loss exit`). A definition without a contract records `{ kind: \"entry\" }`." }, "state": { "type": "string", "enum": [ "pending", "deferred", "accepted", "retrying", "succeeded", "partial", "failed", "uncertain", "rejected", "canceled", "skipped", "coalesced" ], "description": "This automation run's state: `pending` waiting to start, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to an agent run, `retrying` waiting to try again before its deadline, `succeeded` it did what it was asked, `partial` only some of it went through, `failed` it moved nothing it was asked to, `uncertain` money may have moved and how it ended is not known yet, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before starting, `skipped` an earlier automation run was still active or it was missed, `coalesced` merged into a newer match." }, "reason": { "description": "Why the automation run is in this state, when there is one to give. A run that failed or went through only in part gives one of `unavailable`, `insufficient_funds`, `quote_rejected`, `not_authorized`, `not_executed` or `condition_passed`.", "type": [ "string", "null" ] }, "runNumber": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Which of its automation's runs this is, counting from 1, the number its run limit counts. Null for a run that is no scheduled or triggered firing of its own, such as an exit check selling a position. Show this, not `deliverySequence`." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this automation run was recorded." }, "deliveryDeadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest this automation run could still start." }, "deadlineAt": { "description": "The latest this run may still try, once it has started: the earliest of its delivery deadline, the windows its owner signed and its next firing. Null or absent for a run that never started, or one from before this field. Use it, not `deliveryDeadline`, to say how long a run had.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "nextAttemptAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the next attempt to start this automation run is due." }, "lastAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When this automation run was last tried, when it has been." }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many attempts to start this automation run there have been." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation this automation run works in, once it has one." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The agent run this automation run started, once it has one." }, "runStatus": { "anyOf": [ { "type": "string", "enum": [ "running", "paused", "completed", "failed", "aborted" ] }, { "type": "null" } ], "description": "That agent run's status, once it has one: `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "runError": { "description": "Why the agent run failed, when it did.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals this automation run's agent run is waiting on." }, "solana": { "description": "For a Solana trading automation, the admitted trade and its observed result. Absent or null before it acts and for other automations. Read this result independently of runStatus.", "anyOf": [ { "$ref": "#/components/schemas/AutomationRunSolana" }, { "type": "null" } ] }, "perps": { "anyOf": [ { "$ref": "#/components/schemas/AutomationRunPerps" }, { "type": "null" } ], "description": "For a perps automation, the order this run placed or the margin it added, with Hyperliquid's answer. Null for any other automation, and until the run acts." } }, "required": [ "id", "deliverySequence", "automationId", "definitionVersion", "activationEpoch", "name", "prompt", "evidence", "selection", "state", "reason", "runNumber", "createdAt", "deliveryDeadline", "nextAttemptAt", "lastAttemptAt", "attempts", "conversationId", "runId", "runStatus", "runError", "pendingApprovals", "perps" ], "description": "One time an automation ran or was due to run: why, its delivery state, and the agent run it started, if any." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "AutomationRunSolana": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "buy" }, "request": { "$ref": "#/components/schemas/SolanaBuyInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; an agent run completing does not prove that money moved." } }, "required": [ "id", "kind", "request", "outcome" ] }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The Solana activity item’s id, for its receipt in History." }, "kind": { "type": "string", "const": "sell" }, "request": { "$ref": "#/components/schemas/SolanaSellInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "The observed financial result. Null until there is one; a partial result may leave SOL in the Solana account." } }, "required": [ "id", "kind", "request", "outcome" ] } ], "description": "The Solana trade this automation run admitted, with its observed financial result." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaOperationDetail": { "type": "object", "properties": { "side": { "type": "string", "enum": [ "buy", "sell", "fund", "withdraw" ], "description": "Which Solana operation this is: a buy, a sell, a fund or a withdrawal." }, "token": { "description": "The token bought or sold; absent for a fund or a withdrawal.", "$ref": "#/components/schemas/SolanaToken" }, "account": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The agent's own Solana account the operation used." }, "transactions": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." }, "description": "Every transaction the operation signed, in the order it signed them. A multi-coin sale lists here only its one transfer back: each coin's swaps are under its own entry of `sales`." }, "paid": { "description": "What the operation spent, once known.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "received": { "description": "What the operation received, once it landed or settled.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solLeftLamports": { "description": "SOL the operation left in the Solana account, in lamports: what a partial outcome left behind.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "sales": { "description": "Present only on a multi-coin sale's outcome: each sale in the order it ran. `received` is what the whole sale returned.", "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The coin this sale sold, or was to sell.", "$ref": "#/components/schemas/SolanaToken" }, "state": { "type": "string", "enum": [ "sold", "not_sold", "uncertain" ], "description": "`sold` once its swap landed; `not_sold` when it ended without selling anything (refused before any signature, every attempt failed or expired, or the sale stopped before it); `uncertain` while an attempt of it may still land: never sign it again." }, "paid": { "description": "What this sale sold, once its swap landed: the token's exact amount.", "type": "object", "properties": { "asset": { "type": "string", "enum": [ "usdc", "sol", "token" ], "description": "`usdc` is the stablecoin a buy or fund paid (one USDC or USDT holding of the agent wallet, counted one raw unit for one) or the USDC on NEAR a sale or withdrawal returned, `sol` is SOL, `token` is the operation's own token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact amount, in the asset's smallest unit." } }, "required": [ "asset", "amountRaw" ] }, "solGainedLamports": { "description": "The SOL this sale's landed swap added to the Solana account, in lamports, before the one transfer back.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "transactions": { "description": "This coin's swap attempts the sale signed, in the order it signed them; absent while none was signed.", "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "swap", "sweep" ], "description": "`swap` trades on Jupiter; `sweep` sends SOL back to the agent wallet through 1Click." }, "signature": { "type": "string", "minLength": 64, "maxLength": 88, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "A Solana transaction signature, which is also its id: base58 text of 64 bytes." }, "state": { "type": "string", "enum": [ "signed", "dispatching", "landed", "failed", "expired", "uncertain" ], "description": "`signed` and `dispatching` are not yet sent or not yet seen; `landed` succeeded on chain, `failed` landed with an error, `expired` provably never will; `uncertain` is not yet known: never sign it again." }, "feeLamports": { "description": "The network fee the transaction paid, in lamports, once it landed.", "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "purpose", "signature", "state" ], "description": "One signed Solana transaction of this operation." } } }, "required": [ "token", "state" ], "description": "One coin of a multi-coin sale, and what became of it." } } }, "required": [ "side", "account", "transactions" ], "description": "What one Solana operation did on chain." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "AutomationRunPerps": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "order", "description": "A reduce-only order on the automation's position." }, "order": { "description": "The exact order the run placed: the coin, side, size and worst price (`entry.price`) this firing allowed.", "$ref": "#/components/schemas/PerpsOrderInput" }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/PerpsOrderOutcome" }, { "type": "null" } ], "description": "Hyperliquid's answer, with each placement's fill. Null while the order is being sent or its answer is still being checked; the run never sends it twice." } }, "required": [ "kind", "order", "outcome" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "margin", "description": "Margin moved from the agent wallet to the perps account." }, "transfer": { "description": "The exact USDC amount the run moved, in six-decimal units, and its loss bound.", "$ref": "#/components/schemas/PerpsTransferInput" }, "outcome": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_progress" }, "operationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The persisted financial operation still owned by its durable executor." } }, "required": [ "status", "operationId" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "no_trade", "description": "The request resolved without attempting a financial action." } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "refused", "description": "The financial command refused execution under its authority or safety checks." }, "scope": { "type": "string", "enum": [ "authority", "request", "transient", "insufficient_funds", "request_frozen", "verification", "stale_evidence", "account_busy", "conflict", "paused", "held", "withdrawn", "spend_cap_reached", "no_signing_authority", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unavailable", "buy_too_small", "reserve_required", "loss_bound_exceeded", "token_blocked" ], "description": "The bounded category of the refusal; no provider text, account details or amounts are exposed here. `buy_too_small` (a Solana buy below its minimum), `reserve_required` (it would spend the SOL the Solana account keeps for fees) and `loss_bound_exceeded` (no route returned at least the approved minimum) can be corrected by asking the user for other terms; `token_blocked` means the token's own rules, or its missing price, keep it from trading through fin; `route_unavailable` means the requested financial route was not available; `nothing_freed` means a cash-out's withdrawal found nothing its exit freed to bring home." } }, "required": [ "status", "scope" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "settled", "pending", "partial", "refunded", "not_executed" ], "description": "The financial outcome: settled, unresolved, mixed or incomplete, refunded, or conclusively not executed. An outcome can still be waiting for receipts; the trade's or withdrawal's `status` says whether it is final." }, "reason": { "description": "Present when execution was restricted to a mode that cannot sign or move funds.", "type": "string", "const": "signing_disabled" }, "stopped": { "description": "Present only on a partial outcome whose run refused a later leg before it was claimed: the planned action the run stopped on and the bounded reason it never started.", "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] }, "blocked": { "description": "Unclaimed actions blocked before dispatch, with unique indices disjoint from all actual legs.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "reason": { "type": "string", "enum": [ "lineage_unavailable", "consent_invalid", "allowance_exhausted", "spend_cap_reached", "position_unknown", "exit_not_reached", "selection_mismatch", "action_mismatch", "request_frozen", "insufficient_funds", "evidence_unavailable", "inventory_stale", "plan_conflict", "leg_order", "quote_invalid", "payload_invalid", "account_busy", "expired", "credentials_unavailable", "execution_paused", "automation_held", "authority_withdrawn", "perps_disabled", "prediction_disabled", "not_available_in_region", "no_account", "withdrawal_too_small", "withdrawal_reserve_required", "nothing_freed", "order_invalid", "route_unsupported", "route_changed", "solana_disabled", "token_unpriced", "token_mismatch", "token_freezable", "token_transfer_hook", "token_permanent_delegate", "token_non_transferable", "token_default_frozen", "token_transfer_fee", "token_pausable", "token_unknown_extension", "token_not_sellable", "route_invalid", "loss_bound_exceeded", "reserve_required", "buy_too_small", "swap_already_landed", "solana_unavailable" ], "description": "The bounded category the stopped leg was refused with; no provider text, account details or amounts." } }, "required": [ "index", "reason" ] } }, "legs": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 15, "description": "The leg's zero-based position in the frozen plan." }, "state": { "type": "string", "enum": [ "claimed", "signed", "uncertain", "settled", "refunded", "not_executed" ], "description": "The recorded execution or settlement state of this actual leg." } }, "required": [ "index", "state" ] }, "description": "The actual execution legs represented by this outcome; unattempted planned legs have no invented receipt." }, "solana": { "description": "Present only on a Solana operation's outcome: what it paid, received and signed on Solana. `legs` are its 1Click legs.", "$ref": "#/components/schemas/SolanaOperationDetail" } }, "required": [ "status", "legs" ] } ] }, { "type": "null" } ], "description": "How the transfer ended. Null while it is still under way." } }, "required": [ "kind", "transfer", "outcome" ] } ], "description": "What one run of a perps automation did on Hyperliquid: the reduce-only order it placed or the margin it added, with the answer it got." }, "PerpsOrderInput": { "type": "object", "properties": { "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "The position this order opens, adds to, reduces or protects. A reduce-only entry on a long position sells." }, "size": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "Exact size in the coin, at most the market's `szDecimals` places." }, "leverage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ], "description": "Leverage the user chose for this market, at most the market's maximum. Required for an entry that is not reduce-only; null otherwise. Never assume it: ask the user." }, "marginMode": { "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin with every cross position, `isolated` puts only this position's own margin at risk (perps_margin_update adds or removes it later). Present exactly when leverage is; an isolated-only market (perps_markets `onlyIsolated`) takes `isolated`. Never assume it: ask the user. Absent on orders approved before margin modes existed, which were cross.", "type": "string", "enum": [ "cross", "isolated" ] }, "entry": { "anyOf": [ { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The limit price; for an immediate (`Ioc`) order, the worst price it may fill at." }, "timeInForce": { "type": "string", "enum": [ "Gtc", "Ioc", "Alo" ], "description": "`Ioc` fills now within `price` and cancels the rest (a market order), `Gtc` rests until filled or cancelled, `Alo` rests only as a maker order." }, "reduceOnly": { "type": "boolean", "description": "True to only reduce or close the existing position, never open or add." } }, "required": [ "price", "timeInForce", "reduceOnly" ] }, { "type": "null" } ], "description": "The order itself; null for take-profit and stop-loss on the existing position only." }, "takeProfit": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only take-profit, or null." }, "stopLoss": { "anyOf": [ { "$ref": "#/components/schemas/PerpsTrigger" }, { "type": "null" } ], "description": "A reduce-only stop-loss, or null." }, "trailingStop": { "description": "A reduce-only trailing stop, placed after the order (or alone on the existing position); absent or null for none. It carries no builder fee.", "anyOf": [ { "$ref": "#/components/schemas/PerpsTrailingStop" }, { "type": "null" } ] } }, "required": [ "coin", "asset", "side", "size", "leverage", "entry", "takeProfit", "stopLoss" ], "description": "One exact Hyperliquid order on the agent's own account, with optional exits." }, "PerpsTrigger": { "type": "object", "properties": { "triggerPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The mark price that fires this exit." }, "limitPrice": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "The worst price the exit may fill at once fired; it executes as a market order within it." } }, "required": [ "triggerPrice", "limitPrice" ], "description": "A reduce-only market exit on the same size: fires at triggerPrice and fills no worse than limitPrice." }, "PerpsTrailingStop": { "type": "object", "properties": { "retracement": { "anyOf": [ { "type": "object", "properties": { "percent": { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in percent: `2` is 2%." } }, "required": [ "percent" ], "description": "Trail by a percentage of the best mark price." }, { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$", "description": "How far the mark price may reverse from its best since activation, in price units." } }, "required": [ "price" ], "description": "Trail by a fixed price distance." } ], "description": "How far the mark price may reverse from its best before the stop fires." }, "activationPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})(\\.[0-9]{0,11}[1-9])?$" }, { "type": "null" } ], "description": "The mark price that starts the trailing; null to trail from placement." } }, "required": [ "retracement", "activationPrice" ], "description": "A reduce-only market exit on the same size that follows the mark price as it moves in the position's favour and fires once it reverses by the retracement." }, "PerpsOrderOutcome": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "placed", "rejected", "uncertain", "cancelled", "applied", "not_executed" ], "description": "`placed` Hyperliquid accepted the order (see each placement), `rejected` it accepted none (or refused the margin change), `uncertain` the answer was lost and the host reconciles what is still unknown by client order id (a trailing stop with no answer only when one order matches its terms; a margin change from the account's own transaction list), `cancelled` the cancellation took effect, `applied` the margin change took effect, `not_executed` nothing was signed." }, "placements": { "maxItems": 4, "type": "array", "items": { "$ref": "#/components/schemas/PerpsPlacementOutcome" }, "description": "Each placement's own answer, in the order's order: entry, take-profit, stop-loss, then trailing stop." }, "reason": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Why nothing was placed or the cancellation did not take effect, in Hyperliquid's or the host's words; null otherwise." } }, "required": [ "status", "placements", "reason" ], "description": "The result of one approved perps order, cancellation or margin change." }, "PerpsPlacementOutcome": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "entry", "take_profit", "stop_loss", "trailing_stop" ], "description": "Which part of the order: `entry`, `take_profit`, `stop_loss` or `trailing_stop`." }, "cloid": { "anyOf": [ { "type": "string", "pattern": "^0x[0-9a-f]{32}$" }, { "type": "null" } ], "description": "The client order id it is reconciled by; null for a trailing stop, which Hyperliquid gives none and the host matches by its terms instead." }, "state": { "type": "string", "enum": [ "filled", "resting", "triggered_pending", "triggered", "cancelled", "rejected", "unknown" ], "description": "`filled` executed (possibly partly; see `filledSize`), `resting` waits on the book, `triggered_pending` is an exit waiting for its trigger, `triggered` is an exit whose trigger fired and became a market order (its fill is in the account's fills, not here), `rejected` never placed, `unknown` not yet known: never resubmit it." }, "oid": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Hyperliquid's order id once it named one; null for a trigger it answered without one, or an answer not yet known." }, "filledSize": { "description": "How much filled, in the coin, as Hyperliquid wrote it; null when nothing filled or it did not say.", "type": [ "string", "null" ] }, "averagePrice": { "description": "The average fill price, as Hyperliquid wrote it; null when it did not say.", "type": [ "string", "null" ] }, "error": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "description": "Hyperliquid's own refusal text for this placement; null otherwise." } }, "required": [ "role", "cloid", "state", "oid", "filledSize", "averagePrice", "error" ], "description": "What one placement of an order came to on Hyperliquid." }, "PerpsTransferInput": { "type": "object", "properties": { "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount in six-decimal atomic units in either direction: 5 USDC is \"5000000\". A withdrawal returns USDC. A funding spends it from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT) that alone covers it, never split across holdings, or, when it pays with a coin, that coin's value of it; Hyperliquid receives USDC. Never supply an address." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Explicit maximum value loss in basis points, including provider fees and any swap or cross-chain hop of the USDC, USDT or coin a funding spends. Required; no default." }, "payWith": { "description": "A funding only, approved in chat as one call: the coin it pays with instead of a USDC or USDT holding, and the most of it it may spend. A withdrawal never carries it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "amountRaw", "maxValueLossBps" ], "description": "An exact transfer between the agent's own wallet and its perps account, which holds USDC." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # List automation readings 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. `GET /v1/users/{userId}/automations/{automationId}/readings` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "since", "required": false, "description": "The earliest reading to return. Defaults to 30 days before `until`." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "until", "required": false, "description": "The latest reading to return. Defaults to now." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID/readings' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The automation's readings. ```json { "description": "The automation's readings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationReadings" } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.listReadings", "summary": "List automation readings", "tags": [ "automations" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "since", "required": false, "description": "The earliest reading to return. Defaults to 30 days before `until`." }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "in": "query", "name": "until", "required": false, "description": "The latest reading to return. Defaults to now." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation's readings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationReadings" } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "AutomationReadings": { "type": "object", "properties": { "data": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "description": "The reader's name in the rule, `rule.readers[].name`." }, "readerId": { "type": "string", "description": "The source recipe it reads, as `rule.readers[].readerId` names it." }, "latest": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the source says this reading was true." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "One source observation's data, as the provider or the sender sent it. Bounded to 10 levels of nesting and 260 entries." } }, "required": [ "at", "data" ] }, { "type": "null" } ], "description": "The reader's most recent good reading in the window; null when it has none." }, "fields": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "array", "items": { "type": "string" }, "description": "The key path into the reading the rule compares, as in its condition." }, "points": { "maxItems": 240, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the source says this value was true." }, "value": { "type": "string", "description": "The value exactly as the source wrote it: a decimal string." } }, "required": [ "at", "value" ] }, "description": "The field's values in the window, oldest first: at most 240, the last reading of each equal slice of the window." } }, "required": [ "path", "points" ] }, "description": "Each field the rule's condition compares from this reader." } }, "required": [ "binding", "readerId", "latest", "fields" ] }, "description": "One entry for each reader the automation's rule binds, in the rule's order." } }, "required": [ "data" ], "description": "What each source an automation reads reported over a window: its latest reading and the values of the fields its rule compares." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Rotate the webhook secret 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. `POST /v1/users/{userId}/automations/{automationId}/rotate-webhook-secret` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID/rotate-webhook-secret' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The new webhook secret and where it is received. ```json { "description": "The new webhook secret and where it is received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "The new webhook secret. Shown once; it cannot be read back later." }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The new secret's id." }, "path": { "type": "string", "description": "The path this automation's webhook receives requests on." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The definition version this secret was minted for." } }, "required": [ "secret", "keyId", "path", "definitionVersion" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `automation_paused` — the automation is paused; resume it first - `automation_has_no_webhook` — the automation does not run on incoming events, so it has no webhook - `automation_changed` — the automation changed while this request was handled; read it again and retry ```json { "description": "The operation lost to the current state.\n\n- `automation_paused` — the automation is paused; resume it first\n- `automation_has_no_webhook` — the automation does not run on incoming events, so it has no webhook\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 410 The resource still exists and stays readable, but can no longer take this request. - `automation_deleted` — the automation was deleted ```json { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `automation_deleted` — the automation was deleted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.rotateWebhookSecret", "summary": "Rotate the webhook secret", "tags": [ "automations" ], "description": "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.", "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The new webhook secret and where it is received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "The new webhook secret. Shown once; it cannot be read back later." }, "keyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The new secret's id." }, "path": { "type": "string", "description": "The path this automation's webhook receives requests on." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The definition version this secret was minted for." } }, "required": [ "secret", "keyId", "path", "definitionVersion" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_paused` — the automation is paused; resume it first\n- `automation_has_no_webhook` — the automation does not run on incoming events, so it has no webhook\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "410": { "description": "The resource still exists and stays readable, but can no longer take this request.\n\n- `automation_deleted` — the automation was deleted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Backtest an automation 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. `POST /v1/users/{userId}/automations/backtest` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` — A user's session token, from Create a session. ## Path parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "draft" ] }, "definition": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Only the user's instructions for each later run, preserved exactly with their constraints; monitoring conditions belong in rule." }, "rule": { "$ref": "#/components/schemas/AutomationRuleInput" }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "Which contract template this is.", "enum": [ "near_intents_transfer" ] }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Exchange one asset for another; custody never leaves the agent wallet.", "enum": [ "swap" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "additionalProperties": false, "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "additionalProperties": false, "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell when the asset is this far ABOVE the automation's average cost.", "enum": [ "take_profit" ] }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "additionalProperties": false, "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell when the asset is this far BELOW the automation's average cost.", "enum": [ "stop_loss" ] }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "additionalProperties": false, "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled.", "enum": [ "harvest_every" ] }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "additionalProperties": false, "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Return an asset to the account that owns the agent wallet.", "enum": [ "withdraw_to_owner" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "additionalProperties": false, "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "additionalProperties": false, "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route.", "enum": [ "withdraw_transfer" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "additionalProperties": false, "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "additionalProperties": false, "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "additionalProperties": false, "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer.", "enum": [ "send" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "additionalProperties": false, "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "additionalProperties": false, "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "additionalProperties": false, "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ], "additionalProperties": false } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "additionalProperties": false, "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "additionalProperties": false, "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dependency_graph" ] }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ], "additionalProperties": false } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ], "additionalProperties": false }, { "$ref": "#/components/schemas/PerpsAutomationContractInput" }, { "$ref": "#/components/schemas/PredictionAutomationContractInput" }, { "oneOf": [ { "$ref": "#/components/schemas/SolanaBuyContractInput" }, { "$ref": "#/components/schemas/SolanaSellContractInput" } ], "description": "A standing Solana grant: an exact buy, or a sale of a fraction of the holding for USDC, made exactly as approved each time the automation fires." } ], "description": "Standing authority for the runs this automation fires: a NEAR Intents transfer contract, a perps automation that opens, reduces or adds margin to the agent's own Hyperliquid position, a Polymarket buy or sale of one outcome, or a Solana buy or sell made exactly as approved." }, "maxSigningDelaySeconds": { "description": "Required with a contract and omitted without one: the owner's approved maximum delay after a firing during which its run may obtain signatures, in seconds; separate from delivery lateness and signature lifetime.", "type": "integer", "minimum": 1, "maximum": 86400 }, "missedRun": { "type": "string", "enum": [ "skip", "ask" ], "description": "What happens to a run that can't go through before its deadline: `skip` counts it and keeps the schedule, `ask` pauses the automation until its owner decides. A failure only the owner can fix pauses either way." } }, "required": [ "name", "prompt", "rule" ], "additionalProperties": false } }, "required": [ "kind", "definition" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "saved" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "kind", "automationId" ], "additionalProperties": false } ] }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "resolution": { "type": "string", "enum": [ "hourly", "daily" ] }, "timing": { "type": "string", "enum": [ "preserved", "sampled" ] }, "execution": { "type": "string", "enum": [ "contract_terms", "triggers_only" ], "description": "Select triggers_only for a discretionary prompt whose concrete trades are unresolved. contract_terms hypothetically executes the fixed proposed trade terms; it does not simulate model decisions or discretionary instructions." }, "initialHoldings": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ], "additionalProperties": false } }, "funding": { "description": "Select strategy_budget to set aside a finite starting budget from entry sizes and run limits at opening historical prices. Requires empty initialHoldings and cannot be combined with contributeInputs: true. Omit both automatic options to use an explicitly supplied starting portfolio. No live wallet balance is read.", "type": "string", "enum": [ "strategy_budget" ] }, "contributeInputs": { "description": "When true, start empty and hypothetically supply the input assets for each successfully modeled fixed purchase, valued at its fill time. Requires empty initialHoldings and omitted funding. Contributions are capital, not profit; exits receive no new capital. False or omission leaves the existing funding or explicit portfolio behavior unchanged.", "type": "boolean" }, "costBps": { "type": "integer", "minimum": 0, "maximum": 300 } }, "required": [ "target", "startAt", "endAt", "resolution", "timing", "execution", "initialHoldings", "costBps" ], "additionalProperties": false } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/automations/backtest' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The historical estimate and its data limitations. ```json { "description": "The historical estimate and its data limitations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "estimated", "trigger_only", "unavailable", "incomplete" ] }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4096 }, { "type": "null" } ] }, "metrics": { "anyOf": [ { "type": "object", "properties": { "startingValueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "contributedValueUsdDecimal": { "description": "Total external input contributions valued at their modeled fills; contributions are excluded from profit.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "endingValueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "pnlUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "returnPercentDecimal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, { "type": "null" } ], "description": "Net profit divided by starting value plus total contributed value, times 100. Null when no capital was invested; this is not an annualized or time-weighted return." }, "maxDrawdownPercentDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Largest sampled peak-to-trough fall. Contribution-funded estimates use a flow-adjusted index rounded down at each mark to 36 decimal places; financial amounts and trade decisions remain exact." }, "holdValueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "totalCostUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "required": [ "startingValueUsdDecimal", "endingValueUsdDecimal", "pnlUsdDecimal", "returnPercentDecimal", "maxDrawdownPercentDecimal", "holdValueUsdDecimal", "totalCostUsdDecimal" ] }, { "type": "null" } ] }, "counts": { "type": "object", "properties": { "evaluations": { "type": "integer", "minimum": 0, "maximum": 250000 }, "firings": { "type": "integer", "minimum": 0, "maximum": 250000 }, "filledLegs": { "type": "integer", "minimum": 0, "maximum": 1000 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 250000 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 250000 } }, "required": [ "evaluations", "firings", "filledLegs", "skipped", "unknown" ] }, "throughAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "limitations": { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "scenario": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Only the user's instructions for each later run, preserved exactly with their constraints; monitoring conditions belong in rule." }, "rule": { "$ref": "#/components/schemas/AutomationRule" }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "Which contract template this is.", "enum": [ "near_intents_transfer" ] }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Exchange one asset for another; custody never leaves the agent wallet.", "enum": [ "swap" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell when the asset is this far ABOVE the automation's average cost.", "enum": [ "take_profit" ] }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell when the asset is this far BELOW the automation's average cost.", "enum": [ "stop_loss" ] }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled.", "enum": [ "harvest_every" ] }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Return an asset to the account that owns the agent wallet.", "enum": [ "withdraw_to_owner" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route.", "enum": [ "withdraw_transfer" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer.", "enum": [ "send" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dependency_graph" ] }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "oneOf": [ { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" } ], "description": "A standing Solana grant: an exact buy, or a sale of a fraction of the holding for USDC, made exactly as approved each time the automation fires." } ], "description": "Standing authority for the runs this automation fires: a NEAR Intents transfer contract, a perps automation that opens, reduces or adds margin to the agent's own Hyperliquid position, a Polymarket buy or sale of one outcome, or a Solana buy or sell made exactly as approved." }, "maxSigningDelaySeconds": { "description": "Required with a contract and omitted without one: the owner's approved maximum delay after a firing during which its run may obtain signatures, in seconds; separate from delivery lateness and signature lifetime.", "type": "integer", "minimum": 1, "maximum": 86400 }, "missedRun": { "type": "string", "enum": [ "skip", "ask" ], "description": "What happens to a run that can't go through before its deadline: `skip` counts it and keeps the schedule, `ask` pauses the automation until its owner decides. A failure only the owner can fix pauses either way." }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "resolution": { "type": "string", "enum": [ "hourly", "daily" ] }, "timing": { "type": "string", "enum": [ "preserved", "sampled" ] }, "execution": { "type": "string", "enum": [ "contract_terms", "triggers_only" ], "description": "Select triggers_only for a discretionary prompt whose concrete trades are unresolved. contract_terms hypothetically executes the fixed proposed trade terms; it does not simulate model decisions or discretionary instructions." }, "initialHoldings": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ] } }, "funding": { "description": "Select strategy_budget to set aside a finite starting budget from entry sizes and run limits at opening historical prices. Requires empty initialHoldings and cannot be combined with contributeInputs: true. Omit both automatic options to use an explicitly supplied starting portfolio. No live wallet balance is read.", "type": "string", "enum": [ "strategy_budget" ] }, "contributeInputs": { "description": "When true, start empty and hypothetically supply the input assets for each successfully modeled fixed purchase, valued at its fill time. Requires empty initialHoldings and omitted funding. Contributions are capital, not profit; exits receive no new capital. False or omission leaves the existing funding or explicit portfolio behavior unchanged.", "type": "boolean" }, "costBps": { "type": "integer", "minimum": 0, "maximum": 300 }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "prompt", "rule", "startAt", "endAt", "resolution", "timing", "execution", "initialHoldings", "costBps" ] }, "scenarioHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "dataHash": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "engineVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingChanges": { "maxItems": 128, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "before": { "type": "string", "maxLength": 4096 }, "after": { "type": "string", "maxLength": 4096 } }, "required": [ "path", "before", "after" ] } }, "manifest": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "coingecko" ] }, "resolution": { "type": "string", "enum": [ "hourly", "daily" ] }, "availabilityAssumption": { "type": "string", "minLength": 1, "maxLength": 4096 }, "assetIds": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?!(?:constructor|prototype|__proto__)$)[a-z0-9][a-z0-9._-]*$" } }, "tokenMappings": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "assetId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?!(?:constructor|prototype|__proto__)$)[a-z0-9][a-z0-9._-]*$" } }, "required": [ "tokenId", "decimals", "assetId" ] } }, "firstAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "lastAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "source", "resolution", "availabilityAssumption", "assetIds", "tokenMappings", "firstAt", "lastAt" ] }, "skippedByReason": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128 }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "holdings": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ] } }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "plannedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "filledAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15 }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ] }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ] }, "costUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "required": [ "plannedAt", "filledAt", "actionIndex", "input", "output", "costUsdDecimal" ] } }, "contributions": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the modeled input contribution and purchase settle together." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15 }, "valueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Historical USD value of the contributed input tokens at the modeled fill, before trading costs." } }, "required": [ "tokenId", "decimals", "amountRaw", "at", "actionIndex", "valueUsdDecimal" ] } }, "equity": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "valueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "contributedValueUsdDecimal": { "description": "Cumulative external contributions through this point, present for contribution-funded estimates. Subtract it and the starting value from portfolio value to chart profit.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "required": [ "at", "valueUsdDecimal" ] } } }, "required": [ "status", "reason", "metrics", "counts", "throughAt", "limitations", "scenario", "scenarioHash", "dataHash", "engineVersion", "timingChanges", "manifest", "skippedByReason", "holdings", "trades", "equity" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin - `permission_required` — the verified credential is not permitted to make this call ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `automation_changed` — the automation changed while this request was handled; read it again and retry ```json { "description": "The operation lost to the current state.\n\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limit refused the request; wait for `Retry-After` when it is sent. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` - `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After ```json { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.backtest", "summary": "Backtest an automation", "tags": [ "automations" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "draft" ] }, "definition": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Only the user's instructions for each later run, preserved exactly with their constraints; monitoring conditions belong in rule." }, "rule": { "$ref": "#/components/schemas/AutomationRuleInput" }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "Which contract template this is.", "enum": [ "near_intents_transfer" ] }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Exchange one asset for another; custody never leaves the agent wallet.", "enum": [ "swap" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "additionalProperties": false, "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "additionalProperties": false, "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell when the asset is this far ABOVE the automation's average cost.", "enum": [ "take_profit" ] }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "additionalProperties": false, "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell when the asset is this far BELOW the automation's average cost.", "enum": [ "stop_loss" ] }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "additionalProperties": false, "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled.", "enum": [ "harvest_every" ] }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "additionalProperties": false, "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Return an asset to the account that owns the agent wallet.", "enum": [ "withdraw_to_owner" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "additionalProperties": false, "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "additionalProperties": false, "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route.", "enum": [ "withdraw_transfer" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "additionalProperties": false, "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "additionalProperties": false, "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "additionalProperties": false, "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer.", "enum": [ "send" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "additionalProperties": false, "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "additionalProperties": false, "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "additionalProperties": false, "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ], "additionalProperties": false }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ], "additionalProperties": false } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "additionalProperties": false, "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ], "additionalProperties": false } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "additionalProperties": false, "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "additionalProperties": false, "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dependency_graph" ] }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ], "additionalProperties": false } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ], "additionalProperties": false }, { "$ref": "#/components/schemas/PerpsAutomationContractInput" }, { "$ref": "#/components/schemas/PredictionAutomationContractInput" }, { "oneOf": [ { "$ref": "#/components/schemas/SolanaBuyContractInput" }, { "$ref": "#/components/schemas/SolanaSellContractInput" } ], "description": "A standing Solana grant: an exact buy, or a sale of a fraction of the holding for USDC, made exactly as approved each time the automation fires." } ], "description": "Standing authority for the runs this automation fires: a NEAR Intents transfer contract, a perps automation that opens, reduces or adds margin to the agent's own Hyperliquid position, a Polymarket buy or sale of one outcome, or a Solana buy or sell made exactly as approved." }, "maxSigningDelaySeconds": { "description": "Required with a contract and omitted without one: the owner's approved maximum delay after a firing during which its run may obtain signatures, in seconds; separate from delivery lateness and signature lifetime.", "type": "integer", "minimum": 1, "maximum": 86400 }, "missedRun": { "type": "string", "enum": [ "skip", "ask" ], "description": "What happens to a run that can't go through before its deadline: `skip` counts it and keeps the schedule, `ask` pauses the automation until its owner decides. A failure only the owner can fix pauses either way." } }, "required": [ "name", "prompt", "rule" ], "additionalProperties": false } }, "required": [ "kind", "definition" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "saved" ] }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "kind", "automationId" ], "additionalProperties": false } ] }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "resolution": { "type": "string", "enum": [ "hourly", "daily" ] }, "timing": { "type": "string", "enum": [ "preserved", "sampled" ] }, "execution": { "type": "string", "enum": [ "contract_terms", "triggers_only" ], "description": "Select triggers_only for a discretionary prompt whose concrete trades are unresolved. contract_terms hypothetically executes the fixed proposed trade terms; it does not simulate model decisions or discretionary instructions." }, "initialHoldings": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ], "additionalProperties": false } }, "funding": { "description": "Select strategy_budget to set aside a finite starting budget from entry sizes and run limits at opening historical prices. Requires empty initialHoldings and cannot be combined with contributeInputs: true. Omit both automatic options to use an explicitly supplied starting portfolio. No live wallet balance is read.", "type": "string", "enum": [ "strategy_budget" ] }, "contributeInputs": { "description": "When true, start empty and hypothetically supply the input assets for each successfully modeled fixed purchase, valued at its fill time. Requires empty initialHoldings and omitted funding. Contributions are capital, not profit; exits receive no new capital. False or omission leaves the existing funding or explicit portfolio behavior unchanged.", "type": "boolean" }, "costBps": { "type": "integer", "minimum": 0, "maximum": 300 } }, "required": [ "target", "startAt", "endAt", "resolution", "timing", "execution", "initialHoldings", "costBps" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "in": "path", "name": "userId", "required": true, "description": "Your id for the user: the `userId` you sent to Create a user. It must be the session's user." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The historical estimate and its data limitations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "estimated", "trigger_only", "unavailable", "incomplete" ] }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4096 }, { "type": "null" } ] }, "metrics": { "anyOf": [ { "type": "object", "properties": { "startingValueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "contributedValueUsdDecimal": { "description": "Total external input contributions valued at their modeled fills; contributions are excluded from profit.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "endingValueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "pnlUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "returnPercentDecimal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, { "type": "null" } ], "description": "Net profit divided by starting value plus total contributed value, times 100. Null when no capital was invested; this is not an annualized or time-weighted return." }, "maxDrawdownPercentDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Largest sampled peak-to-trough fall. Contribution-funded estimates use a flow-adjusted index rounded down at each mark to 36 decimal places; financial amounts and trade decisions remain exact." }, "holdValueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "totalCostUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "required": [ "startingValueUsdDecimal", "endingValueUsdDecimal", "pnlUsdDecimal", "returnPercentDecimal", "maxDrawdownPercentDecimal", "holdValueUsdDecimal", "totalCostUsdDecimal" ] }, { "type": "null" } ] }, "counts": { "type": "object", "properties": { "evaluations": { "type": "integer", "minimum": 0, "maximum": 250000 }, "firings": { "type": "integer", "minimum": 0, "maximum": 250000 }, "filledLegs": { "type": "integer", "minimum": 0, "maximum": 1000 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 250000 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 250000 } }, "required": [ "evaluations", "firings", "filledLegs", "skipped", "unknown" ] }, "throughAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "limitations": { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "scenario": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 8192, "description": "Only the user's instructions for each later run, preserved exactly with their constraints; monitoring conditions belong in rule." }, "rule": { "$ref": "#/components/schemas/AutomationRule" }, "contract": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "Which contract template this is.", "enum": [ "near_intents_transfer" ] }, "actions": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Exchange one asset for another; custody never leaves the agent wallet.", "enum": [ "swap" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "exit": { "description": "Optional exit guard: this action sells only when the asset's price in its output token crosses the automation's own average cost by the approved amount.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell when the asset is this far ABOVE the automation's average cost.", "enum": [ "take_profit" ] }, "gainBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far above the average cost the price must be, in basis points." } }, "required": [ "kind", "gainBps" ], "description": "A take-profit exit: sell once the price is up this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell when the asset is this far BELOW the automation's average cost.", "enum": [ "stop_loss" ] }, "lossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "How far below the average cost the price must be, in basis points." } }, "required": [ "kind", "lossBps" ], "description": "A stop-loss exit: sell once the price is down this much on average cost." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Take profits on a schedule: sell only the gain every this many days, counted from the last harvest that settled, or from the first deposit that settled.", "enum": [ "harvest_every" ] }, "days": { "type": "string", "pattern": "^[1-9]\\d{0,2}$", "description": "How many days apart harvests are, 7 to 365, as a decimal string: \"7\" weekly, \"30\" monthly." } }, "required": [ "kind", "days" ], "description": "A scheduled harvest: only on a gain_of_position exit selling a curated yield vault's share token (earn_vaults). Every `days` days it sells only the gain, if there is any, and the automation keeps running." } ] } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Return an asset to the account that owns the agent wallet.", "enum": [ "withdraw_to_owner" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." } }, "required": [ "kind", "input", "quantity", "output" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Pay the exact approved destination through the provider’s chain or Intents transfer route.", "enum": [ "withdraw_transfer" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "chain", "intents" ], "description": "A native blockchain transfer or a signed transfer within an Intents ledger." }, "network": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$", "description": "Exact network identifier from wallet capabilities; near-intents and near-intents-confidential are ledgers, not the NEAR blockchain." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,256}$", "description": "Exact network address, preserving case and any routing metadata encoded in its native address format. Names must be resolved before approval." }, "memo": { "type": "null", "description": "Standalone routing memos are unsupported; routing must be encoded in the approved address." } }, "required": [ "rail", "network", "address", "memo" ], "description": "The exact approved payout rail, network and address." }, "minimumReceivedRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Minimum acceptable payout in output-asset atomic units, or null when the approved all-in loss bound alone sets the floor." }, "maxFeeRaw": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, { "type": "null" } ], "description": "Optional separate withdrawal fee cap in output-asset atomic units; null means undisclosed, while all-in loss and minimum receive remain enforced." } }, "required": [ "kind", "input", "quantity", "output", "recipient", "minimumReceivedRaw", "maxFeeRaw" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Not executable, and refused in new contracts: pay an address with withdraw_transfer.", "enum": [ "send" ] }, "input": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action spends: pinned to one token, or any token the agent wallet holds." }, "quantity": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend an exact amount of the input token.", "enum": [ "exact_input_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact input amount, in the input token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the input token, not its USD value: exactly 5 USDC at decimals 6 is amountRaw \"5000000\". No floating-point arithmetic or bash." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a USD-denominated value of the input token.", "enum": [ "exact_input_value_usd" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})(?:\\.\\d{1,18})?$", "description": "The USD value to spend, as a decimal string." } }, "required": [ "kind", "value" ], "description": "A USD value of the input token: \"$5 worth of USDC\" is value \"5\", never exactly 5 USDC. The host converts it at live prices." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Receive an exact amount of the output token.", "enum": [ "exact_output_tokens" ] }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The exact output amount, in the output token's smallest unit." } }, "required": [ "kind", "amountRaw" ], "description": "An exact quantity of the output token, scaled by its verified decimals; the host calculates the input." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend everything the agent wallet holds of the input asset.", "enum": [ "all_of_input" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Spend a fraction of the input asset.", "enum": [ "fraction_of_input" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to spend, in basis points of the input asset." } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell a fraction of this automation's own position in the input asset.", "enum": [ "fraction_of_position" ] }, "bps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The fraction to sell, in basis points of this automation's own position; 10000 is all of it." } }, "required": [ "kind", "bps" ], "description": "A fraction of what THIS automation's own settled fills still hold of the input asset, never of the wallet balance; only on an action with an `exit` guard." }, { "type": "object", "properties": { "kind": { "type": "string", "description": "Sell only the gain on this automation's own position in the input asset.", "enum": [ "gain_of_position" ] } }, "required": [ "kind" ], "description": "Only the gain on THIS automation's own position, priced in the token its buys paid with; only with a take_profit or harvest_every `exit` guard and a pinned output other than that token." } ], "description": "How much moves: an exact token amount, an exact USD value, an exact output amount, all of the input, or a fraction of it." }, "output": { "anyOf": [ { "type": "object", "properties": { "pinned": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." } }, "required": [ "tokenId", "decimals" ], "description": "The exact token this asset is pinned to." } }, "required": [ "pinned" ] }, { "type": "object", "properties": { "any": { "type": "boolean", "description": "Any token the agent wallet holds; the executor picks one at execution.", "enum": [ true ] } }, "required": [ "any" ] } ], "description": "The asset this action produces: pinned to one token, or left open." }, "recipient": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Which chain the destination address is on." }, "address": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,128}$", "description": "The destination address on that chain." } }, "required": [ "chain", "address" ], "description": "The pinned destination this action pays." } }, "required": [ "kind", "input", "quantity", "output", "recipient" ] } ] }, "description": "The actions this contract authorizes, executed in order." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this contract's authority expires." }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many times this contract may be executed before it is exhausted." }, "maxTotalInput": { "description": "Optional total cap on what all executions together may spend, per input token, in raw units. A $500 budget paid in USDC is 500 USDC. Every action input must be pinned and capped.", "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most this contract may spend of this token in total, across every execution, in the token's smallest unit." } }, "required": [ "tokenId", "decimals", "amountRaw" ], "description": "One capped input token and its total spend ceiling." } }, "bounds": { "type": "object", "properties": { "maxValueLossBps": { "type": "string", "pattern": "^(0|[1-9]\\d{0,4})$", "description": "The most value an execution may give up to price movement and fees together, in basis points; 0 allows no loss." }, "maxSignatureLifetimeSeconds": { "type": "integer", "minimum": 1, "maximum": 259500, "description": "Explicit maximum lifetime of each released transfer signature, in seconds. 1Click confidential swaps require up to 259500 seconds (72 hours 5 minutes). This does not extend the execution window or approval validity." } }, "required": [ "maxValueLossBps", "maxSignatureLifetimeSeconds" ], "description": "The value-loss and signature-lifetime limits every execution must respect." }, "execution": { "description": "Optional explicit recovery authority, signed with these exact actions and bounds; omitted on historical approvals.", "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ordered", "parallel_independent" ], "description": "Ordered actions run in approved order. Parallel-independent actions run up to four concurrently after the complete initially funded request is reserved." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "maxPreparationAttempts", "dispatchWindowSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dependency_graph" ] }, "dependencies": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "maxItems": 16, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 } }, "description": "One row per requested action, listing its sorted unique predecessor action indices. A successor requires confirmed predecessor settlement. Every action must be funded from initial holdings." }, "maxPreparationAttempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "The maximum unsigned preparation attempts for each approved action, including its first attempt." }, "dispatchWindowSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "description": "The maximum dispatch window in seconds for this operation, from when its approval opened: exactly 1200 for a new chat request, and up to its signed deadline for an automation's grant. Closing dispatch never proves a submitted transfer did not move; observation continues." } }, "required": [ "mode", "dependencies", "maxPreparationAttempts", "dispatchWindowSeconds" ] } ] } }, "required": [ "type", "actions", "validUntil", "maxExecutions", "bounds" ] }, { "$ref": "#/components/schemas/PerpsAutomationContract" }, { "$ref": "#/components/schemas/PredictionAutomationContract" }, { "oneOf": [ { "$ref": "#/components/schemas/SolanaBuyContract" }, { "$ref": "#/components/schemas/SolanaSellContract" } ], "description": "A standing Solana grant: an exact buy, or a sale of a fraction of the holding for USDC, made exactly as approved each time the automation fires." } ], "description": "Standing authority for the runs this automation fires: a NEAR Intents transfer contract, a perps automation that opens, reduces or adds margin to the agent's own Hyperliquid position, a Polymarket buy or sale of one outcome, or a Solana buy or sell made exactly as approved." }, "maxSigningDelaySeconds": { "description": "Required with a contract and omitted without one: the owner's approved maximum delay after a firing during which its run may obtain signatures, in seconds; separate from delivery lateness and signature lifetime.", "type": "integer", "minimum": 1, "maximum": 86400 }, "missedRun": { "type": "string", "enum": [ "skip", "ask" ], "description": "What happens to a run that can't go through before its deadline: `skip` counts it and keeps the schedule, `ask` pauses the automation until its owner decides. A failure only the owner can fix pauses either way." }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "resolution": { "type": "string", "enum": [ "hourly", "daily" ] }, "timing": { "type": "string", "enum": [ "preserved", "sampled" ] }, "execution": { "type": "string", "enum": [ "contract_terms", "triggers_only" ], "description": "Select triggers_only for a discretionary prompt whose concrete trades are unresolved. contract_terms hypothetically executes the fixed proposed trade terms; it does not simulate model decisions or discretionary instructions." }, "initialHoldings": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ] } }, "funding": { "description": "Select strategy_budget to set aside a finite starting budget from entry sizes and run limits at opening historical prices. Requires empty initialHoldings and cannot be combined with contributeInputs: true. Omit both automatic options to use an explicitly supplied starting portfolio. No live wallet balance is read.", "type": "string", "enum": [ "strategy_budget" ] }, "contributeInputs": { "description": "When true, start empty and hypothetically supply the input assets for each successfully modeled fixed purchase, valued at its fill time. Requires empty initialHoldings and omitted funding. Contributions are capital, not profit; exits receive no new capital. False or omission leaves the existing funding or explicit portfolio behavior unchanged.", "type": "boolean" }, "costBps": { "type": "integer", "minimum": 0, "maximum": 300 }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "prompt", "rule", "startAt", "endAt", "resolution", "timing", "execution", "initialHoldings", "costBps" ] }, "scenarioHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "dataHash": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "engineVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "timingChanges": { "maxItems": 128, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "before": { "type": "string", "maxLength": 4096 }, "after": { "type": "string", "maxLength": 4096 } }, "required": [ "path", "before", "after" ] } }, "manifest": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "coingecko" ] }, "resolution": { "type": "string", "enum": [ "hourly", "daily" ] }, "availabilityAssumption": { "type": "string", "minLength": 1, "maxLength": 4096 }, "assetIds": { "maxItems": 16, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?!(?:constructor|prototype|__proto__)$)[a-z0-9][a-z0-9._-]*$" } }, "tokenMappings": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "assetId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?!(?:constructor|prototype|__proto__)$)[a-z0-9][a-z0-9._-]*$" } }, "required": [ "tokenId", "decimals", "assetId" ] } }, "firstAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "lastAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "source", "resolution", "availabilityAssumption", "assetIds", "tokenMappings", "firstAt", "lastAt" ] }, "skippedByReason": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128 }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "holdings": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ] } }, "trades": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "plannedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "filledAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15 }, "input": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ] }, "output": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" } }, "required": [ "tokenId", "decimals", "amountRaw" ] }, "costUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "required": [ "plannedAt", "filledAt", "actionIndex", "input", "output", "costUsdDecimal" ] } }, "contributions": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$" }, "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "When the modeled input contribution and purchase settle together." }, "actionIndex": { "type": "integer", "minimum": 0, "maximum": 15 }, "valueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$", "description": "Historical USD value of the contributed input tokens at the modeled fill, before trading costs." } }, "required": [ "tokenId", "decimals", "amountRaw", "at", "actionIndex", "valueUsdDecimal" ] } }, "equity": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "valueUsdDecimal": { "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" }, "contributedValueUsdDecimal": { "description": "Cumulative external contributions through this point, present for contribution-funded estimates. Subtract it and the starting value from portfolio value to chart profit.", "type": "string", "pattern": "^-?(0|[1-9]\\d{0,77})(\\.\\d{1,36})?$" } }, "required": [ "at", "valueUsdDecimal" ] } } }, "required": [ "status", "reason", "metrics", "counts", "throughAt", "limitations", "scenario", "scenarioHash", "dataHash", "engineVersion", "timingChanges", "manifest", "skippedByReason", "holdings", "trades", "equity" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `automation_changed` — the automation changed while this request was handled; read it again and retry", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "AutomationRuleInput": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ], "additionalProperties": false }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ], "additionalProperties": false }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ], "additionalProperties": false } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode" ], "additionalProperties": false } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ], "additionalProperties": false } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "additionalProperties": false, "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ], "additionalProperties": false } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "additionalProperties": false, "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ], "additionalProperties": false }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "additionalProperties": false, "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "additionalProperties": false, "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ], "additionalProperties": false } }, "required": [ "intervalSeconds", "readers" ], "additionalProperties": false }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "additionalProperties": false, "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ], "additionalProperties": false }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "additionalProperties": false, "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValueInput": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValueInput" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" } } ] }, "PerpsAutomationContractInput": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationActionInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "additionalProperties": false, "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationActionInput": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "additionalProperties": false, "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "additionalProperties": false, "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "additionalProperties": false, "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PredictionAutomationContractInput": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "additionalProperties": false, "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationActionInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "additionalProperties": false, "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationActionInput": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "additionalProperties": false, "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "additionalProperties": false, "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaBuyContractInput": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInputInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "additionalProperties": false, "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaBuyInputInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaTokenInput" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "additionalProperties": false, "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPaymentInput" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "additionalProperties": false, "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaTokenInput": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "additionalProperties": false, "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPaymentInput": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "additionalProperties": false, "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaSellContractInput": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInputInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "additionalProperties": false, "description": "An approved Solana sell, executed only exactly as approved." }, "SolanaSellInputInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaTokenInput" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "additionalProperties": false, "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "additionalProperties": false, "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "additionalProperties": false, "description": "One sell of a Solana token held in the agent's own Solana account." }, "AutomationRule": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "The rule schema's version; always `1`." }, "delivery": { "default": { "overlap": "queue", "maxPendingOccurrences": 100 }, "oneOf": [ { "type": "object", "properties": { "overlap": { "type": "string", "const": "queue", "description": "Queue a new occurrence and run it once the active one finishes." }, "maxPendingOccurrences": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many occurrences may wait in the queue, not counting the one currently active, including one whose run is itself waiting on an approval." } }, "required": [ "overlap", "maxPendingOccurrences" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "coalesce", "description": "Close the occurrence already pending as `coalesced` and record the new match as a fresh occurrence, rather than queuing a second." } }, "required": [ "overlap" ] }, { "type": "object", "properties": { "overlap": { "type": "string", "const": "skip", "description": "Drop a new match while an occurrence is already active." } }, "required": [ "overlap" ] } ], "description": "What happens when a new occurrence is ready before the previous one has finished." }, "maxDeliveryLatenessSeconds": { "default": 86400, "description": "How long a new occurrence may wait to be delivered before its deadline passes and it is refused, in seconds.", "type": "integer", "minimum": 1, "maximum": 86400 }, "maxEvaluationGapSeconds": { "default": 600, "description": "The longest gap allowed between evaluations before `firing.mode: rising_edge` treats its history as broken and waits for a fresh baseline, in seconds.", "type": "integer", "minimum": 1, "maximum": 2678400 }, "wakes": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "at", "description": "A one-time wake at an exact moment; exhausted after that check, even if its condition is false." }, "runAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "The exact moment this wake fires, as an ISO 8601 timestamp with an offset." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "runAt", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "interval", "description": "A wake that repeats on a fixed elapsed interval." }, "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 44640, "description": "How often this wake repeats, in minutes." }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "intervalMinutes", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "calendar", "description": "A wake on a recurring calendar schedule: local times, weekdays, months and days of the month." }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The IANA time zone a calendar wake's local times are interpreted in." }, "localTimes": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": "The times of day this wake fires, each in 24-hour `HH:MM` form, in `timeZone`." }, "weekdays": { "default": [ 1, 2, 3, 4, 5, 6, 7 ], "description": "Which ISO weekdays this wake fires on, 1 (Monday) through 7 (Sunday). Defaults to every day.", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "months": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "description": "Which months this wake fires in, 1 (January) through 12 (December). Defaults to every month.", "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 } }, "monthDays": { "default": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "description": "Which days of the month this wake fires on, 1 through 31. Defaults to every day.", "minItems": 1, "maxItems": 31, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 31 } }, "misfire": { "default": { "mode": "latest", "maxLatenessSeconds": null }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "skip", "description": "Drop a wake the engine could not evaluate in time; wait for the next one." }, "graceSeconds": { "default": 5, "description": "How late this wake may still run before it counts as missed, in seconds.", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "mode", "graceSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "latest", "description": "Run once for the most recently missed wake, dropping any earlier ones." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all", "description": "Run once for every missed wake, oldest first." }, "maxLatenessSeconds": { "default": null, "description": "How late a missed wake may still run, in seconds; null for no limit.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2678400 }, { "type": "null" } ] } }, "required": [ "mode", "maxLatenessSeconds" ] } ], "description": "What happens when the engine could not evaluate this wake on time." }, "evaluationTime": { "default": "detection_time", "description": "Which moment this wake is evaluated as of: `scheduled_time` the time it was due, `detection_time` when the engine actually ran it.", "type": "string", "enum": [ "scheduled_time", "detection_time" ] } }, "required": [ "kind", "timeZone", "localTimes", "weekdays", "months", "monthDays", "misfire", "evaluationTime" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "event", "description": "A wake evaluated each time a matching custom webhook event arrives." }, "eventType": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "The event `type` this wake matches; a live webhook delivery of a different type is ignored before it reaches the condition." }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "path": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,63}$" }, "description": "The keys to walk, in order, from an observation's top level down to this field." }, "valueType": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean", "description": "A true/false value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "string", "description": "A text value." } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "integer", "description": "A whole-number value, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "decimal", "description": "An exact decimal value, as text, compared exactly." }, "unit": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The unit an integer or decimal value is measured in, as the source or literal declares it." } }, "required": [ "type", "unit" ] } ], "description": "What type this field's value has, and the unit it carries when it has one." }, "optional": { "description": "Whether the provider may genuinely not observe this field, rather than fail to read it. When true, a missing value resolves a condition over it to `missing_field` and the rule's verdict to `unknown`, rather than zero, null or false.", "type": "boolean" } }, "required": [ "path", "valueType" ], "description": "One data field an event or a source's observation carries: where it lives, and its type." }, "description": "The data fields an event of this type is declared to carry." } }, "required": [ "kind", "eventType", "fields" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "reader_update", "description": "A wake evaluated each time the named reader delivers a fresh observation." }, "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "kind", "binding" ] } ] }, "description": "Occasions to evaluate the rule's condition: alternatives, not an AND of conditions. At most one clock and one event stream." }, "readers": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "readerId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The installed source operation's id, as listed by List automation data sources." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." }, "delivery": { "description": "Use reviewed push updates; omit for periodic snapshots.", "type": "string", "const": "push" }, "pollIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 2147483, "description": "Polling cadence, or subscription lease/reconciliation cadence for push delivery, in seconds." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum retained input age at evaluation, matching requirement.maxAgeSeconds when present. Snapshots use observation time; events use trusted receipt time. Collection separately enforces the provider's acquisition-age guarantee." }, "requirement": { "type": "object", "properties": { "maxLatencySeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 2147483 }, { "type": "null" } ], "description": "The target delay between an observation and its delivery, in seconds; null when delivery has no target deadline." }, "maxAgeSeconds": { "type": "integer", "minimum": 1, "maximum": 86400, "description": "Maximum acceptable input age at evaluation, matching the reader's maxAgeSeconds, measured from the provider's own observation time. The selected provider's acquisition guarantee must fit within this limit and does not reduce this evaluation window." }, "allowDegradedLatency": { "type": "boolean", "description": "Whether delivery slower than the target delay is still accepted." }, "maxAcceptedLatencySeconds": { "description": "The slowest delivery still accepted, in seconds, when `allowDegradedLatency` is set.", "type": "integer", "minimum": 1, "maximum": 2147483 } }, "required": [ "maxLatencySeconds", "maxAgeSeconds", "allowDegradedLatency" ], "description": "What a reader needs from its source: how fresh an answer must be, and whether a slower one is still acceptable." } }, "required": [ "name", "readerId", "config", "pollIntervalSeconds", "maxAgeSeconds" ] }, "description": "The named source bindings this rule reads from, referenced by `condition` and by each `reader_update` wake's `binding`." }, "condition": { "description": "The rule's condition tree, up to 8 levels deep and 128 nodes total, built from five node kinds: `{op:\"bool\", value}` a fixed true/false leaf; `{op:\"compare\", comparator, left, right}` one of `eq`/`ne`/`lt`/`lte`/`gt`/`gte` between two operands — `lt`/`lte`/`gt`/`gte` require both operands to be `integer` or `decimal`, and both sides must share the same type and, for `integer`/`decimal`, the same unit; `{op:\"all\", args}` / `{op:\"any\", args}` AND/OR over one or more child nodes; `{op:\"not\", arg}` negates one child node. An operand is either `{kind:\"field\", binding, path}` — a bound reader's name and the key path into its data — or `{kind:\"literal\", type, value, unit?}` with `type` one of `boolean`/`string`/`integer`/`decimal` (`integer`/`decimal` values are exact decimal strings and carry `unit`)." }, "exit": { "description": "The exit watch, when this rule's automation has exit actions on its contract. Present exactly when the contract has an exit action.", "type": "object", "properties": { "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 2678400, "description": "How often this automation re-checks its exit guards, in seconds; at least 60 and at most 2678400 (31 days), the same span an interval wake may cover. Recommend 300." }, "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the asset this automation bought, in USD." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding in `readers` that prices the token this automation pays with, in USD." } }, "required": [ "asset", "quote" ], "description": "The two price bindings each exit guard is measured against; both must be the reviewed USD token-price operation." }, "push": { "description": "Additional push-delivered USD prices that may check exits between periodic 1Click checks.", "type": "object", "properties": { "readers": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." }, "quote": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding name a rule or a plan gives one configured source." } }, "required": [ "asset", "quote" ], "description": "The supplementary price bindings for the bought asset and its paying token." } }, "required": [ "readers" ] } }, "required": [ "intervalSeconds", "readers" ] }, "firing": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "each_match", "rising_edge" ], "description": "When a qualifying evaluation fires: `each_match` fires on every qualifying evaluation, including the first; `rising_edge` fires only on a known false-to-true transition." }, "repeat": { "type": "string", "enum": [ "once", "repeating" ], "description": "Whether this rule fires at most once, or keeps watching after it fires." }, "maxRuns": { "description": "Maximum deliverable runs recorded for this automation across pauses and resumes. Missed or refused deliveries do not count; recorded runs count even if later canceled, coalesced or failed. Omit for no finite limit beyond repeat=once.", "type": "integer", "minimum": 1, "maximum": 1000000 }, "initial": { "type": "string", "enum": [ "baseline", "fire_if_true" ], "description": "How `rising_edge` treats the first known state: `baseline` records it without firing, `fire_if_true` fires immediately if it is already true." }, "cooldownSeconds": { "type": "integer", "minimum": 0, "maximum": 2678400, "description": "The minimum time between firings, in seconds; it does not require the condition to stay true that whole time. For `rising_edge`, a false-to-true edge that lands inside cooldown is discarded, not queued: it is not replayed once cooldown ends, so the rule needs an entirely fresh edge after cooldown lapses before it fires again — simply remaining true past the cooldown boundary does not trigger a firing." } }, "required": [ "mode", "repeat", "initial", "cooldownSeconds" ], "description": "How this rule turns a qualifying evaluation into a firing: which ones count, how often, and how many." }, "news": { "description": "Present only on a news exit: the owner's own words, which Fin's news judge reads new stories against. Its rule is fixed: one `news.judged` event wake, no readers, the judged condition and one firing, over a reduce-only perps contract.", "type": "object", "properties": { "condition": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The owner's condition in their own words, exactly as they said it, such as `right before Anthropic's IPO`. Never paraphrased: the judge reads the news against these words." }, "match": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[\\p{L}\\p{N} .'&-]+$", "description": "A few words every story the judge reads must contain in its headline or summary, such as `Anthropic IPO`: a broad filter, not the condition. The judge decides from the condition." } }, "required": [ "condition", "match" ] }, "maxSnapshotSkewSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "The most that bound readers' observation times may disagree before evaluation reports `snapshot_skew`, in seconds." } }, "required": [ "schemaVersion", "delivery", "maxDeliveryLatenessSeconds", "maxEvaluationGapSeconds", "wakes", "readers", "condition", "firing", "maxSnapshotSkewSeconds" ], "description": "One automation's rule: when it wakes, what condition it evaluates, and how it fires." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "PerpsAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "perps_automation", "description": "Which authorization contract this is." }, "coin": { "type": "string", "pattern": "^(?:xyz:)?[A-Za-z0-9]{1,20}$", "description": "The market's coin name exactly as perps_markets lists it, such as `BTC` or `xyz:TSLA`." }, "asset": { "type": "integer", "minimum": 0, "maximum": 1099999, "description": "The market's asset id exactly as perps_markets lists it for that coin." }, "position": { "type": "string", "enum": [ "long", "short" ], "description": "The position the action is for. `open` acts only while the agent holds nothing on this coin; `reduce` and `add_margin` act only while it holds this side, and nothing happens otherwise." }, "action": { "$ref": "#/components/schemas/PerpsAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may act under this approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "coin", "asset", "position", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one perps automation: open the agent's own position while it holds nothing on the coin, reduce or close it, or add margin to its own account, each time its rule fires, up to its limits." }, "PerpsAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "reduce", "description": "Reduce or close the position." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the position to close, in basis points: 10000 closes it all." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires." } }, "required": [ "kind", "fractionBps", "maxSlippageBps" ], "description": "Close part or all of the position with a reduce-only market order." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "add_margin", "description": "Add margin to the perps account." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC moved from the agent wallet into the perps account, six decimals: 5 USDC is \"5000000\"." }, "maxValueLossBps": { "type": "integer", "minimum": 0, "maximum": 300, "description": "Maximum value lost to fees moving it, in basis points." } }, "required": [ "kind", "amountRaw", "maxValueLossBps" ], "description": "Fund the agent's own perps account from its agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "open", "description": "Open the position at market." }, "notionalUsd": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The position's size in US dollars at the mark when it fires, at most two places: a $200 position is \"200\". The size in the coin is this over the mark, rounded down to the market's size precision." }, "leverage": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Leverage the user chose for this market, at most the market's maximum. Never assume it: ask the user." }, "marginMode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "How the position is margined, which the user chose with the leverage: `cross` shares the account's margin, `isolated` risks only this position's own. An isolated-only market takes `isolated`. Never assume it: ask the user." }, "maxSlippageBps": { "type": "integer", "minimum": 1, "maximum": 500, "description": "The worst fill allowed, in basis points from the mark when it fires; the take-profit and stop-loss fill within the same bound of their trigger." }, "takeProfitPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native take-profit this far from the mark when it opens, in percent of price in the position's favour (\"10\" is 10%), or null for none." }, "stopLossPercent": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]?)(\\.[0-9]{0,3}[1-9])?$" }, { "type": "null" } ], "description": "A native stop-loss this far from the mark when it opens, in percent of price against the position (\"5\" is 5%), or null for none." } }, "required": [ "kind", "notionalUsd", "leverage", "marginMode", "maxSlippageBps", "takeProfitPercent", "stopLossPercent" ], "description": "Open the position with a market order, only while the agent holds nothing on this coin, optionally protected by a native take-profit and stop-loss." } ], "description": "What a perps automation does each time its rule fires: open the named position while the agent holds nothing on its coin, reduce the named position, or add margin to the agent's own perps account." }, "PredictionAutomationContract": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction_automation", "description": "Which authorization contract this is." }, "market": { "type": "object", "properties": { "marketId": { "type": "string", "pattern": "^[1-9][0-9]{0,19}$", "description": "The market's id exactly as prediction_market returns it." }, "conditionId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The market's conditionId exactly as prediction_market returns it." }, "assetId": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$", "description": "The outcome's CLOB token id, exactly the assetId prediction_market lists for that outcome. Yes and No are different tokens." }, "marketQuestion": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "The market's question exactly as prediction_market returns it." }, "outcome": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The outcome's name exactly as prediction_market returns it." } }, "required": [ "marketId", "conditionId", "assetId", "marketQuestion", "outcome" ], "description": "The one Polymarket outcome this automation trades." }, "action": { "$ref": "#/components/schemas/PredictionAutomationAction" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "How many firings may trade under this approval; a buy spends at most maxExecutions × amountUsdDecimal in all." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The deadline after which this approval authorizes nothing." } }, "required": [ "type", "market", "action", "maxExecutions", "validUntil" ], "description": "A standing approval for one Polymarket automation: buy one outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price, each time its rule fires, up to its limits." }, "PredictionAutomationAction": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buy", "description": "Buy shares of the outcome." }, "amountUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,2})?$", "description": "The USD each firing spends before fees, to the cent: \"50\" is $50. Each buy is an immediate order that fills what it can at once and cancels the rest." }, "maxPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The most a share may cost, as the market's chance: \"0.32\" never pays more than 32¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "amountUsdDecimal", "maxPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Buy the outcome with a USD budget at no more than a maximum price." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sell", "description": "Sell shares of the outcome." }, "fractionBps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How much of the agent's holding of the outcome each firing sells, in basis points: 10000 sells it all." }, "minPriceUsdDecimal": { "type": "string", "pattern": "^0\\.[0-9]{1,4}$", "description": "The least a share may sell for, as the market's chance: \"0.7\" never sells below 70¢ a share. Use a price on the market's tick." }, "maxFeeUsdDecimal": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,6})(\\.[0-9]{1,6})?$", "description": "The most each firing may pay Polymarket in fees, in USD: \"1\" is $1." } }, "required": [ "kind", "fractionBps", "minPriceUsdDecimal", "maxFeeUsdDecimal" ], "description": "Sell a share of the agent's holding of the outcome at no less than a minimum price." } ], "description": "What a Polymarket automation does each time its rule fires: buy the outcome with a USD budget at no more than a maximum price, or sell a share of the agent's holding of it at no less than a minimum price." }, "SolanaBuyContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_buy", "description": "Which authorization contract this is." }, "buy": { "description": "The exact approved token, payment, all-in loss bound and SOL top-up cap, and, for a buy whose funding pays with a coin, that coin and the most of it it may spend.", "$ref": "#/components/schemas/SolanaBuyInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "buy", "maxExecutions", "validUntil" ], "description": "An approved Solana buy, executed only exactly as approved." }, "SolanaBuyInput": { "type": "object", "properties": { "token": { "description": "The exact token to buy.", "$ref": "#/components/schemas/SolanaToken" }, "pay": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "usdc", "description": "Pay from one USDC or USDT holding of the agent wallet (USDC on NEAR, Base, Arbitrum, Ethereum or Solana, or USDT on NEAR; any USDC that covers it before USDT), moved to Solana as SOL first." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact USDC or USDT to spend, in six-decimal atomic units: $50 is \"50000000\". At least 5 (\"5000000\"); a smaller buy is refused." } }, "required": [ "kind", "amountRaw" ], "description": "Spend an exact amount of USDC or USDT from the agent wallet." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "sol", "description": "Pay with SOL already in the agent's Solana account." }, "lamports": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact SOL to spend, in lamports (nine decimals): 0.5 SOL is \"500000000\"." } }, "required": [ "kind", "lamports" ], "description": "Spend an exact amount of SOL the agent's Solana account already holds." } ], "description": "What the buy spends, as an exact input amount. Buying an exact number of tokens is not supported." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." }, "maxSolTopUpUsdcRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most extra USDC or USDT the funding may add to keep SOL in the Solana account for network fees, in six-decimal atomic units: \"0\" for none, at most \"1000000\" (1 USDC). Must be \"0\" when paying with SOL." }, "payWith": { "description": "A buy paid in dollars and approved in chat as one call: the coin its funding pays with instead of a USDC or USDT holding, and the most of it it may spend, the SOL top-up included. Never SOL. A buy from a token's page refuses it.", "$ref": "#/components/schemas/VenueFundingPayment" } }, "required": [ "token", "pay", "maxValueLossBps", "maxSolTopUpUsdcRaw" ], "description": "One exact-input buy of a Solana token through the agent's own Solana account." }, "SolanaToken": { "type": "object", "properties": { "mint": { "type": "string", "minLength": 32, "maxLength": 44, "pattern": "^[1-9A-HJ-NP-Za-km-z]+$", "description": "The token's mint address, exactly as solana_token_search or solana_token returned it. Never a ticker." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "The mint's decimals, exactly as returned with the mint." }, "tokenProgram": { "type": "string", "enum": [ "spl_token", "token_2022" ], "description": "The program that owns the mint, exactly as returned with the mint: `spl_token` or `token_2022`." } }, "required": [ "mint", "decimals", "tokenProgram" ], "description": "One Solana token, pinned by its mint, its decimals and its token program." }, "VenueFundingPayment": { "type": "object", "properties": { "tokenId": { "type": "string", "maxLength": 256, "pattern": "^(?:nep141|nep245|1cs_v1):[\\x21-\\x7e]+$", "description": "The exact ledger asset identifier, including its token standard namespace." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 38, "description": "How many decimal places the token's smallest unit represents." }, "maxInputRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "The most of the coin this funding may spend, in its smallest unit: the approved dollars at the price read when the approval opened, plus 5%." } }, "required": [ "tokenId", "decimals", "maxInputRaw" ], "description": "The coin this funding pays with and the most of it it may spend, as the owner approved them. Absent: the funding spends one USDC or USDT holding." }, "SolanaSellContract": { "type": "object", "properties": { "type": { "type": "string", "const": "solana_sell", "description": "Which authorization contract this is." }, "sell": { "description": "The exact approved token, amount, proceeds and all-in loss bound.", "$ref": "#/components/schemas/SolanaSellInput" }, "maxExecutions": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many times this grant may execute: 1 for a one-shot approval." }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this grant's authority expires; for a one-shot approval, the approval's own expiry." } }, "required": [ "type", "sell", "maxExecutions", "validUntil" ], "description": "An approved Solana sell, executed only exactly as approved." }, "SolanaSellInput": { "type": "object", "properties": { "token": { "description": "The exact token to sell.", "$ref": "#/components/schemas/SolanaToken" }, "amount": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "exact", "description": "Sell an exact amount of the token." }, "amountRaw": { "type": "string", "pattern": "^(0|[1-9]\\d{0,38})$", "description": "Exact amount of the token to sell, in its smallest unit (scaled by the token's decimals)." } }, "required": [ "kind", "amountRaw" ], "description": "Sell an exact amount of the token." }, { "type": "object", "properties": { "kind": { "type": "string", "const": "fraction", "description": "Sell a share of what the Solana account holds of the token." }, "bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "The share to sell, in basis points of the account's balance of the token: all of it is 10000, half is 5000." } }, "required": [ "kind", "bps" ], "description": "Sell a share of the account's balance of the token." } ], "description": "How much of the token to sell." }, "receive": { "type": "string", "enum": [ "usdc", "sol" ], "description": "`usdc` returns the proceeds to the agent wallet as USDC on NEAR, which is what selling means; `sol` keeps them as SOL in the agent's Solana account." }, "maxValueLossBps": { "type": "integer", "minimum": 1, "maximum": 1500, "description": "Explicit all-in maximum value loss in basis points, from the value paid to the value received, fees and price impact included: at least 1, at most 1500. Required; no default." } }, "required": [ "token", "amount", "receive", "maxValueLossBps" ], "description": "One sell of a Solana token held in the agent's own Solana account." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin\n- `permission_required` — the verified credential is not permitted to make this call", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limit refused the request; wait for `Retry-After` when it is sent.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` — this partner's request quota across all keys and replicas is spent; honour Retry-After", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The service cannot take this right now (draining, a dependency did not answer, or an operator paused the work); `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "fin_session_", "description": "A user's session token, from Create a session." } } } } ``` --- # Send an automation event 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. `POST /api/automations/{id}/webhook` ## Authentication All credentials below are required. - Header: `X-Automation-Key: YOUR_API_KEY` ## Path parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "The automation's id." } ] ``` ## Header parameters ```json [ { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "in": "header", "name": "x-automation-key", "required": true, "description": "The current automation source credential returned once by owner-authorized rotation. It permits ingestion only, never user reads, commands or financial consent." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$", "description": "A caller-chosen id for this event, used to deduplicate exact replays within one activation. Reuse with changed data conflicts." }, "type": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "This event's own `type`, as the sender reports it." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event happened, as the sender reports it." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." } }, "required": [ "id", "type", "occurredAt", "data" ], "additionalProperties": false, "description": "One event, shaped as an automation's inbound webhook receives it: an id, a type, when it happened, and its data." } } }, "description": "One event, shaped as an automation's inbound webhook receives it: an id, a type, when it happened, and its data." } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/api/automations/YOUR_ID/webhook' \ --header 'X-Automation-Key: YOUR_API_KEY' \ --header 'x-automation-key: YOUR_VALUE' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 200 The identical event was already retained. ```json { "description": "The identical event was already retained.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "recorded", "duplicate" ], "description": "`recorded` when the event is new; `duplicate` when the same event `id` with the same content was already received." }, "inputId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The id the event was recorded under, for your logs. Recording an event does not mean its condition matched or that anything ran." } }, "required": [ "status", "inputId" ] } } } } ``` ### 202 The source event was durably retained for evaluation. ```json { "description": "The source event was durably retained for evaluation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "recorded", "duplicate" ], "description": "`recorded` when the event is new; `duplicate` when the same event `id` with the same content was already received." }, "inputId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The id the event was recorded under, for your logs. Recording an event does not mean its condition matched or that anything ran." } }, "required": [ "status", "inputId" ] } } } } ``` ### 400 The authenticated event is invalid. ```json { "description": "The authenticated event is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } } ``` ### 401 The source credential is absent, invalid or no longer current. ```json { "description": "The source credential is absent, invalid or no longer current.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } } ``` ### 409 The event id already identifies different content. ```json { "description": "The event id already identifies different content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } } ``` ### 410 The automation's firing policy is complete. ```json { "description": "The automation's firing policy is complete.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } } ``` ### 413 The request exceeds the maximum body size. ```json { "description": "The request exceeds the maximum body size.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 The source rate limit refused this event; honor Retry-After. ```json { "description": "The source rate limit refused this event; honor Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.receiveEvent", "summary": "Send an automation event", "tags": [ "automations" ], "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$", "description": "A caller-chosen id for this event, used to deduplicate exact replays within one activation. Reuse with changed data conflicts." }, "type": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.:-]{0,79}$", "description": "This event's own `type`, as the sender reports it." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this event happened, as the sender reports it." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" }, "description": "Arbitrary JSON data: an event's data, a reader's configuration, or a source plan's configuration. Bounded to 16 KiB, 8 levels of nesting and 256 entries." } }, "required": [ "id", "type", "occurredAt", "data" ], "additionalProperties": false, "description": "One event, shaped as an automation's inbound webhook receives it: an id, a type, when it happened, and its data." } } }, "description": "One event, shaped as an automation's inbound webhook receives it: an id, a type, when it happened, and its data." }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true, "description": "The automation's id." }, { "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "in": "header", "name": "x-automation-key", "required": true, "description": "The current automation source credential returned once by owner-authorized rotation. It permits ingestion only, never user reads, commands or financial consent." } ], "security": [ { "automationSourceKey": [] } ], "responses": { "200": { "description": "The identical event was already retained.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "recorded", "duplicate" ], "description": "`recorded` when the event is new; `duplicate` when the same event `id` with the same content was already received." }, "inputId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The id the event was recorded under, for your logs. Recording an event does not mean its condition matched or that anything ran." } }, "required": [ "status", "inputId" ] } } } }, "202": { "description": "The source event was durably retained for evaluation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "recorded", "duplicate" ], "description": "`recorded` when the event is new; `duplicate` when the same event `id` with the same content was already received." }, "inputId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The id the event was recorded under, for your logs. Recording an event does not mean its condition matched or that anything ran." } }, "required": [ "status", "inputId" ] } } } }, "400": { "description": "The authenticated event is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } }, "401": { "description": "The source credential is absent, invalid or no longer current.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } }, "409": { "description": "The event id already identifies different content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } }, "410": { "description": "The automation's firing policy is complete.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } }, "413": { "description": "The request exceeds the maximum body size.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "The source rate limit refused this event; honor Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "unauthorized", "automation completed", "invalid event", "event id conflict", "too many events" ], "description": "A source-ingress refusal. Source credential validation precedes event validation; changed event bytes under an existing identity conflict." } }, "required": [ "error" ] } } } } } }, "components": { "schemas": { "AutomationJsonValueInput": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValueInput" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValueInput" } } ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (429) — the user's AI usage budget, or your partner account's AI spend limit, is used up until the next day or month, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (429) — no capacity is free to run this right now; honour `Retry-After`\n- `execution_unavailable` (503) — the service that runs the agent could not take the work; `retryable` says whether to try again\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the automation changed while this request was handled; read it again and retry\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_paused` (409) — the automation is paused; resume it first\n- `automation_has_no_webhook` (409) — the automation does not run on incoming events, so it has no webhook\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (400) — `profile.tools` names a tool this deployment does not have\n- `deployment_paused` (503) — an operator paused this kind of work for the deployment; try again later\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the request key already binds different withdrawal terms, or the current balance cannot cover the requested amount\n- `swap_changed` (409) — the swap cannot be made as asked: an asset is no longer available or the current balance cannot cover the amount; get a new quote\n- `order_changed` (409) — the order can no longer be placed as prepared: the agent wallet no longer holds the amount, an asset is no longer offered, or its minimum no longer matches the assets' precision; prepare it again\n- `prediction_order_changed` (409) — the Polymarket order can no longer be placed as signed: the market closed or stopped taking orders, its price is off the market's tick or its size off Polymarket's minimum, its fee or cost would exceed the signed caps, the Polymarket account cannot cover it, or the signature lapsed before it was placed. Nothing was placed; prepare it again\n- `solana_trade_changed` (409) — the Solana trade can no longer run as signed: the token's decimals or program changed, the agent's Solana account or holdings no longer fit it, another Solana trade is running, or the signature lapsed before it started. Nothing moved; prepare it again\n- `trade_not_recoverable` (409) — the original trade or a recovery attempt remains active or uncertain, its unfinished actions lack conclusive recovery proof, or its remaining proposal can no longer be used\n- `order_not_cancelable` (409) — the limit order can no longer be cancelled: it filled or expired, or the swap provider never took it. Read the order for where it stands\n- `grid_not_active` (409) — the grid is not running, so it cannot be paused: it is already paused, stopping or ended. Read the grid for where it stands\n- `grid_not_paused` (409) — the grid is not paused, so there is nothing to resume. Read the grid for where it stands\n- `suggestion_changed` (409) — the suggestion no longer holds: the account or the market moved since fin made it, the user set it aside, or it cannot be made where the user is now. Say it changed, and read the page's suggestions again\n- `request_key_conflict` (409) — the request identity already binds different terms; retrieve the original resource or use a new identity for a new request\n- `question_not_pending` (409) — the questionnaire has already been answered, closed, or is not awaiting this submission\n- `flag_changed` (409) — the flag's targeting changed since you read it; read it again and retry\n- `group_changed` (409) — the group changed or was deleted since you read it; read it again and retry\n- `group_in_use` (409) — a flag's rules still name this group; take it out of those rules first\n- `group_name_taken` (409) — another group already has this name\n- `agent_wallet_required` (409) — create the agent wallet before opening a perps, prediction-market or Solana account\n- `wallet_account_unsupported` (409) — the user's wallet is an Agent API wallet, whose Intents account is a 0x address this route cannot name; read it with Get wallet account, Get wallet account balances and Open a wallet account session instead\n- `conversation_deleted` (410) — the conversation was deleted; its history stays readable\n- `automation_deleted` (410) — the automation was deleted\n- `grid_ended` (410) — the grid stopped, expired or failed; it stays readable but takes no command. A new grid needs the user's approval in chat\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `perps_disabled` (403) — perps is not enabled for this user\n- `prediction_disabled` (403) — prediction-market trading is not enabled for this user\n- `solana_disabled` (403) — Solana trading is not enabled for this user\n- `no_account` (404) — the user has not opened the account this call reads; open it first\n- `not_available_in_region` (403) — perps funding is unavailable in the user's region for this request; withdrawals remain available\n- `steering_disabled` (403) — steering a working run is not turned on for this user; send the message with Start a run once the run ends\n- `baskets_disabled` (403) — idea baskets are not turned on for this user; hide the Ideas pages and their baskets\n- `basket_buying` (409) — the basket is still buying, so it cannot be deleted yet; try again once its result is in\n- `basket_awaiting_approval` (409) — an approval to buy this basket is still open; decline it in the chat, then delete the basket\n- `basket_step_not_failed` (409) — the step bought, or the basket is not partly bought, so no order can be linked to it; read the basket again\n- `basket_step_linked` (409) — another order is already linked to this step; a link is permanent, so read the basket again\n- `basket_order_not_linkable` (400) — the order cannot stand in for this step: it is not one of the step's `failures[].linkable` orders, or another basket step already holds it\n- `voice_disabled` (403) — voice input is not turned on for this user; let them type instead\n- `voice_unavailable` (503) — this deployment has no speech model, so it cannot transcribe recordings; let the user type instead\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `quote_refused` (400) — 1Click would not quote this request, usually an amount below what it routes or a pair it does not offer; nothing was reserved. Change the amount or the assets and quote again; for a deposit address, no address was issued, so offer another network\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the verified credential is not permitted to make this call\n- `signature_required` (403) — creating the agent wallet needs the user's signature: send the user's signature of `creation.message` from Get the agent wallet as `authorization`\n- `asset_not_withdrawable` (403) — tokenized stocks cannot be withdrawn; sell them first\n- `asset_not_swappable` (403) — the swap names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `asset_not_tradable` (403) — the order names an asset this user cannot buy or trade with this request: a tokenized stock with no `context.country`, or one where tokenized stocks are not available, or bought while buying them is not enabled for the user; or a yield vault's share token bought while the user's `earn` flag is off\n- `solana_token_not_tradable` (403) — Fin won't trade this token: its mint lets someone freeze, move or charge for holdings or pause transfers, it can't be sold back, Fin couldn't read its mint, it has no reliable price, or it is wrapped SOL. A sale is refused only for what would stop it landing\n- `limit_orders_disabled` (403) — limit orders are not enabled for this user\n- `grid_trading_disabled` (403) — grid trading is not enabled for this user, so a paused grid cannot be resumed; pausing and cancelling a grid are never gated\n- `deposit_limit_exceeded` (429) — the deposit would take the agent wallet past the user's deposit limit, or, for a deposit address, the wallet has no room left under it; nothing was recorded. Read `depositLimit.availableCents` from Get balances for how much fits now, and deposit no more than that\n- `policy_change_throttled` (429) — the user's Agent API wallet changed what it allows a few minutes ago, and the NEAR Intents Agent API lets it change again only after a cooldown; nothing was asked or signed, so call again once `Retry-After` has passed\n- `agent_slippage_exceeded` (403) — the user's wallet is an Agent API wallet whose agent signs only trades that lose at most the share of their value its owner allowed (`max_slippage_bps`): fees, price and slippage together, by 1Click's own USD values at the quote's minimum output. This trade's quote loses more, states no USD value, or, before there is a quote, its loss bound is already quoted with more slippage than that (half the bound, plus 1Click's fee at the most it has been seen to take, 20 basis points, before an approval). Very small trades lose more to fixed fees; nothing was signed, so ask again with a larger amount or a smaller loss bound\n- `agent_api_orders_unavailable` (403) — the user's Agent API wallet needs wallet setup to enable limit orders, or the order exceeds this wallet's 168-hour maximum; finish wallet setup or choose at most 168 hours before trying again; nothing was approved or signed\n- `destination_not_allowed` (403) — the user's wallet is an Agent API wallet, whose agent pays a deposit only to itself, to a NEAR Intents account its owner listed (on the confidential ledger) or to an address on a chain its owner listed; allow this one with Add a withdrawal destination (one owner signature), then ask again. A public NEAR Intents account, or an address with no valid spelling on its chain, cannot be paid at all; nothing was signed\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `partner_request_capacity` (429) — this partner's request quota across all keys and replicas is spent; honour Retry-After\n- `partner_run_capacity` (429) — this partner's active run quota is full; honour Retry-After and reuse the same request identity\n- `stream_capacity` (429) — the partner, user or replica has no free stream capacity; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted\n- `invalid_question_answer` (400) — the questionnaire answer does not match its questions or allowed choices\n- `question_closed` (410) — the questionnaire expired or was cancelled\n- `unknown_target` (400) — a rule names a partner, group or user that does not exist, or a user outside the partners the same rule names\n- `scope_invalid` (400) — a subject in the scope is not a subject id, or appears twice\n- `subject_unsupported` (404) — a subject in the scope is not one market briefs cover; list them with List market subjects\n- `brief_not_found` (404) — no market brief job with this id was created with your partner key\n- `briefs_busy` (429) — your market briefs are at their limit of briefs generating at once; retry after `Retry-After`\n- `market_briefs_disabled` (403) — market briefs are not turned on for your partner key\n- `story_not_found` (404) — no market story with this id is current: it never was one, or Fin no longer shows it because its sources were withdrawn or its figures can no longer be read", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_paused", "automation_has_no_webhook", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "swap_changed", "order_changed", "prediction_order_changed", "solana_trade_changed", "trade_not_recoverable", "order_not_cancelable", "grid_not_active", "grid_not_paused", "suggestion_changed", "request_key_conflict", "question_not_pending", "flag_changed", "group_changed", "group_in_use", "group_name_taken", "agent_wallet_required", "wallet_account_unsupported", "conversation_deleted", "automation_deleted", "grid_ended", "credential_expired", "account_disabled", "perps_disabled", "prediction_disabled", "solana_disabled", "no_account", "not_available_in_region", "steering_disabled", "baskets_disabled", "basket_buying", "basket_awaiting_approval", "basket_step_not_failed", "basket_step_linked", "basket_order_not_linkable", "voice_disabled", "voice_unavailable", "provider_unavailable", "quote_refused", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "signature_required", "asset_not_withdrawable", "asset_not_swappable", "asset_not_tradable", "solana_token_not_tradable", "limit_orders_disabled", "grid_trading_disabled", "deposit_limit_exceeded", "policy_change_throttled", "agent_slippage_exceeded", "agent_api_orders_unavailable", "destination_not_allowed", "rate_limited", "partner_request_capacity", "partner_run_capacity", "stream_capacity", "invalid_cursor", "invalid_question_answer", "question_closed", "unknown_target", "scope_invalid", "subject_unsupported", "brief_not_found", "briefs_busy", "market_briefs_disabled", "story_not_found" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "automationSourceKey": { "type": "apiKey", "in": "header", "name": "X-Automation-Key", "description": "An automation's webhook secret, from Rotate the webhook secret. It only sends events to that automation." } } } } ```